> ## Documentation index
> Fetch the complete documentation index at: [llms.txt](../llms.txt)
> Use this file to discover all available pages before exploring further.

# 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

| 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_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.

## Related

- [Projects and runs tools](tools-projects.md): Nine tools to create projects, ask research questions, follow runs, approve plans, and read Sleuth’s answers.
- [Datasets and charts tools](tools-datasets.md): Seven tools to read the datasets and charts a run builds: page through rows, download CSV, compare versions, and get charts as specs or SVG.
- [Plans and approvals](plans-approvals.md): Sleuth shows you what it will build before it builds it. Here is what you approve and how to skip approvals.

*Updated November 9, 2026.*
