This is alpha version of the Scout API. Subject to change.
Overview
This gives you programmatic access to the same agent that powers Scout in the Harmonic product. Ask a question in plain English, get a response back as markdown (or optionally as structured JSON).
Note: We're covering all costs pre-release, and Alpha users will have reasonable usage caps. When we launch, Scout via API will be a separate paid product billed on usage, as servicing this product requires material compute costs.
Getting started
POST /scout/tasks - submit a natural language query, get back a task_id, then poll GET /scout/tasks/{task_id} until status: success, and the response will be in the content field. You'll get markdown by default. The current rate limit is 10/minute or 100/hour, subject to change.
# 1. Kick off the task
PROMPT="Prep me for an intro call with Peec AI. \
Need to know the key details about the company \
+ any notable specifics about the founder. \
Give me a good sense of the major players in their space too, \
and how they relate, so I can reference them"
TASK=$(curl -s -X POST "https://api.harmonic.ai/scout/tasks" \
-H "apikey: $HARMONIC_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg input "$PROMPT" '{input: $input}')")
TASK_ID=$(echo "$TASK" | jq -r .task_id)
echo "Started task $TASK_ID"
# 2. Poll until success, then view results
while true; do
RESULT=$(curl -s "https://api.harmonic.ai/scout/tasks/$TASK_ID" \
-H "apikey: $HARMONIC_API_KEY")
STATUS=$(echo "$RESULT" | tr -d '\000-\037' | jq -r .status)
echo " status: $STATUS"
case "$STATUS" in
success|error|timeout|interrupted) break ;;
esac
sleep 5
done
echo $RESULT
Structured output
If you want structured data, pass a json_schema and Scout will best attempt coerce its answer to match:
curl -X POST "https://api.harmonic.ai/scout/tasks" \
-H "apikey: $HARMONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "Find early engineers at Profound",
"json_schema": {
"type": "object",
"properties": {
"people": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"linkedin_url": {"type": "string"},
"one_liner": {"type": "string"},
"years_at_profound": {"type": "string"}
},
"required": ["name", "linkedin_url", "one_liner"]
}
}
},
"required": ["people"]
}
}
To stream responses instead of poll
1. POST /scout/tasks/stream — start a task and stream it
The first SSE event is {"type": "task_id", "content": "<id>"}; save it in case you need to reconnect. Then you get step and content events, and finally done.
NOTE: json_schema is not supported on this endpoint.
curl -N -X POST "https://api.harmonic.ai/scout/tasks/stream" \
-H "apikey: $HARMONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "Which senior Engineers or principals have left OpenAI in the last 6mo? Where did they go?"}'
2. GET /scout/tasks/{task_id}/stream — reconnect to an in-progress task
Use the task_id from either POST /scout/tasks/stream (first event) or POST /scout/tasks (response body) to reattach after a disconnect.
curl -N "<https://api.harmonic.ai/scout/tasks/><TASK_ID>/stream" \
-H "apikey: $HARMONIC_API_KEY"
Pricing & Usage Management
Scout via API is metered based on token usage, and has consumption-based pricing.
You'll have control and visibility into your spend, including the ability to set monthly limits, view per run costs, and more.