How a research run works
Create a project, send the question, wait for the status to change, handle approvals and clarifications, then read the datasets and the answer.
A research run is Sleuth's analysis for one question, the same one Studio runs when you ask in Analyze. It moves through a set of statuses. Your agent's job is to follow the status and do what each one asks.
The run, step by step
- Create a project.
create_projectwith a name returns aproject_idand statusidle. Reuse the project for follow-up questions on the same topic. - Attach files, if any.
upload_documentbefore you send the question. Files over 10 MB go in through Studio. - Send the question.
send_messagewithmessage. It returns a 202 acknowledgement at once, and the run starts. - Wait for the status to change.
wait_for_updatepolls for you, for 180 seconds by default and up to 300 a call, and returns the full project state withstatus_changedandwaited_seconds. Runs take longer as the plan grows, so keep chaining calls until the status changes. If you pollget_projectyourself, respect itsretry_afterhint. - Act on the status, using the table below.
- Read the results.
get_messagesfor Sleuth's written answer,list_datasetsandget_datasetfor the data, andlist_artifactsfor charts.
Statuses
| Status | What's happening | What your agent does |
|---|---|---|
idle | The project exists and nothing is running. | Send a question. |
processing | Sleuth is reading the question and planning. | Wait. |
awaiting_clarification | Sleuth needs an answer before it can plan. | Read the latest message with get_messages, ask the user, and reply with send_message. |
awaiting_plan_approval | The plan is ready: the steps and the size of the job. | Show the user the plan. Send approve_plan, or reject_plan with feedback. |
awaiting_schema_approval | The columns are ready for review. | Show the user the columns. Send approve_schema, or reject_schema with feedback. |
executing | Sleuth is building the datasets. Credits are used here. | Wait. |
complete | Results are ready. | Read the answer, datasets, and charts. |
failed | The run stopped. A run that fails without results doesn't use credits. | Read the last message and try again, or tell the user to contact Sleuth. |
cancelled | Someone cancelled the run. | Nothing, unless the user wants to start again. |
Approvals
Whether a run pauses for approval depends on how the agent signed in:
- People signed in with OAuth, and personal API keys, follow the user's auto-approve setting in Studio. With it off, runs pause at
awaiting_plan_approvalandawaiting_schema_approval. - Organization API keys approve both gates automatically, so runs go from
processingtoexecutingtocomplete.
When a person is in the loop, show them the plan or the columns before you approve. A headless job on an organization key never pauses, so decide its scope before you send the question. There's no per-run credit cap yet: put the limits in the question itself, like "up to 50 rows and 3 analytical columns," and watch the Usage page.
Approve with send_message and an action, never with a chat message:
send_message({ "project_id": "…", "action": "approve_plan" })
send_message({ "project_id": "…", "action": "reject_schema",
"feedback": "Add a column for the latest readout date" })Cancel a run
send_message with "action": "cancel" stops a run that hasn't finished. Cells already filled keep their credits, and nothing else is charged.
Follow-up questions
Send another send_message to the same project. Questions about results already built don't use credits. A follow-up that needs new rows or columns runs a new plan.
Read results without flooding your context
get_datasetreturns 50 rows by default and up to 2,000 a page. Userow_offsetto page through, andtotal_rowsto know when to stop.download_dataset_csvreturns the whole dataset as CSV text, so save it for when the user wants the file.export_projectreturns everything in the project, with datasets capped at 10,000 rows each. Use it for archiving, not for reading.
Updated November 9, 2026