Start free
Overview

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

  1. Create a project. create_project with a name returns a project_id and status idle. Reuse the project for follow-up questions on the same topic.
  2. Attach files, if any. upload_document before you send the question. Files over 10 MB go in through Studio.
  3. Send the question. send_message with message. It returns a 202 acknowledgement at once, and the run starts.
  4. Wait for the status to change. wait_for_update polls for you, for 180 seconds by default and up to 300 a call, and returns the full project state with status_changed and waited_seconds. Runs take longer as the plan grows, so keep chaining calls until the status changes. If you poll get_project yourself, respect its retry_after hint.
  5. Act on the status, using the table below.
  6. Read the results. get_messages for Sleuth's written answer, list_datasets and get_dataset for the data, and list_artifacts for charts.

Statuses

StatusWhat's happeningWhat your agent does
idleThe project exists and nothing is running.Send a question.
processingSleuth is reading the question and planning.Wait.
awaiting_clarificationSleuth needs an answer before it can plan.Read the latest message with get_messages, ask the user, and reply with send_message.
awaiting_plan_approvalThe 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_approvalThe columns are ready for review.Show the user the columns. Send approve_schema, or reject_schema with feedback.
executingSleuth is building the datasets. Credits are used here.Wait.
completeResults are ready.Read the answer, datasets, and charts.
failedThe 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.
cancelledSomeone 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_approval and awaiting_schema_approval.
  • Organization API keys approve both gates automatically, so runs go from processing to executing to complete.

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_dataset returns 50 rows by default and up to 2,000 a page. Use row_offset to page through, and total_rows to know when to stop.
  • download_dataset_csv returns the whole dataset as CSV text, so save it for when the user wants the file.
  • export_project returns everything in the project, with datasets capped at 10,000 rows each. Use it for archiving, not for reading.