> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seltz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic run

> The full request/response cycle for a single run against the Seltz Agent API, in each language

To get an in-depth, cited answer to a question, start a run with the query,
wait for it to finish, and read the result. This guide demonstrates that workflow
in full.

The [quickstart](/agent/quickstart) shows the shortest path to a result.
This guide walks the same request through in more detail, including what the SDKs'
`create_and_wait` / `createAndWait` hide from you, and the manual poll a
plain REST caller has to do instead.

## 1. Start a run

`create_and_wait` / `createAndWait` call
[`create`](/api-reference/agent/start-run), then poll until the run
finishes, and hand back the completed envelope. cURL has no waiter, so the
same request only starts the run:

<CodeGroup>
  ```python Python theme={null}
  from seltz import Seltz

  client = Seltz(api_key="your-api-key")

  run = client.agent.create_and_wait(
      "What are the three most notable AI-company acquisitions announced in 2026?"
  )
  ```

  ```typescript TypeScript theme={null}
  import { Seltz } from "seltz";

  const client = new Seltz({ apiKey: "your-api-key" });

  let run = await client.agent.createAndWait({
    query: "What are the three most notable AI-company acquisitions announced in 2026?",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.seltz.ai/v1/agent/runs \
    -H "x-api-key: $SELTZ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "What are the three most notable AI-company acquisitions announced in 2026?"}'
  ```
</CodeGroup>

The cURL call returns at once with the run in `pending` state.
[`output`](/api-reference/agent/start-run#response-output-one-of-1) is
present but its fields stay unset until the run reaches a terminal state:

```json theme={null}
{
  "id": "run_01a072afeedf7df2bfe72350dc381785",
  "object": "agent.run",
  "status": "pending",
  "stop_reason": null,
  "created_at": "2026-09-05T17:48:47Z",
  "started_at": null,
  "completed_at": null,
  "request": {
    "query": "What are the three most notable AI-company acquisitions announced in 2026?",
    "output_schema": null
  },
  "output": {
    "text": null,
    "structured": null,
    "sources": [],
    "grounding": []
  }
}
```

## 2. Poll for the result

Retrieve the run by the `id` the create call returned. In Python and
TypeScript, `create_and_wait` / `createAndWait` already did this polling for
you above, so `run` there is already the finished envelope;
[`get`](/api-reference/agent/get-run) is the single check it repeats under
the hood, useful on its own when you want to look a run up independently
instead of holding onto the object `create` returned. Over cURL, this is the
only way to find out whether the run is done:

<CodeGroup>
  ```python Python theme={null}
  run = client.agent.get(run.id)
  ```

  ```typescript TypeScript theme={null}
  run = await client.agent.get(run.id);
  ```

  ```bash cURL theme={null}
  curl "https://api.seltz.ai/v1/agent/runs/run_01a072afeedf7df2bfe72350dc381785" \
    -H "x-api-key: $SELTZ_API_KEY"
  ```
</CodeGroup>

See [Poll for completion](/agent/guides/poll-for-completion) for the full
loop that turns one check into "wait until done," and for `wait`'s options.

Check [`status`](/api-reference/agent/get-run#response-status) before
reading anything from `output`. A run that hasn't finished yet comes back as
`running` (or `pending`), not an error, and `output`'s fields stay unset,
the same status as right after the run is created:

```json theme={null}
{
  "id": "run_01a072afeedf7df2bfe72350dc381785",
  "object": "agent.run",
  "status": "running",
  "stop_reason": null,
  "created_at": "2026-09-05T17:48:47Z",
  "started_at": "2026-09-05T17:48:47Z",
  "completed_at": null,
  "request": {
    "query": "What are the three most notable AI-company acquisitions announced in 2026?",
    "output_schema": null
  },
  "output": {
    "text": null,
    "structured": null,
    "sources": [],
    "grounding": []
  }
}
```

[`started_at`](/api-reference/agent/get-run#response-started-at-one-of-0)
distinguishes `running` from `pending`: it is `null` while
a run waits for a worker, and set the moment one picks up the run. Keep polling
until `status` is `completed`, `failed`, or `cancelled`, or use `wait` /
`createAndWait`, which does exactly this loop for you. Once the status is `completed`, a
completed run's [`output.text`](/api-reference/agent/get-run#response-output-one-of-1)
is a cited Markdown report, with inline `[n]` markers pointing at
[`output.sources`](/api-reference/agent/get-run#response-output-one-of-1):

```json theme={null}
{
  "id": "run_01a072afeedf7df2bfe72350dc381785",
  "object": "agent.run",
  "status": "completed",
  "stop_reason": "finished",
  "created_at": "2026-09-05T17:48:47Z",
  "started_at": "2026-09-05T17:48:47Z",
  "completed_at": "2026-09-05T17:49:05Z",
  "request": {
    "query": "What are the three most notable AI-company acquisitions announced in 2026?",
    "output_schema": null
  },
  "output": {
    "text": "## Three most notable AI-company acquisitions announced in 2026\n\nAssuming “notable” means a combination of deal size, strategic significance, and impact on the AI industry, the leading three are:\n\n1. **SpaceX → Anysphere (Cursor) — $60 billion** (June 16). SpaceX announced an all-stock agreement to acquire Anysphere, the company behind the AI coding platform Cursor, at an implied $60 billion equity value. The transaction would make Anysphere a wholly owned SpaceX subsidiary and represents SpaceX’s major expansion from aerospace and satellite communications into AI software. [1] Crunchbase described it as the largest startup acquisition on record and said it accounted for roughly half of 2026 U.S. venture-backed startup M&A spending at that point. [2]\n\n2. **Nvidia → Hugging Face — about $13 billion** (announced by September 3). Nvidia agreed to acquire Hugging Face, a major platform for AI models, datasets, and applications. It would be Nvidia’s largest outright acquisition, giving the chipmaker greater influence over AI-model distribution while expanding beyond chips into models, developers, and infrastructure. [3] Nvidia said Hugging Face would remain an open platform, with its more than 18 million developers retaining choice over models, cloud providers, and chips. [3]\n\n3. **Qualcomm → Modular — approximately $4 billion** (June). Qualcomm pursued/acquired Modular, an AI software and chip company whose platform lets developers deploy models across different chips without rewriting code. The deal is notable because it forms part of Qualcomm’s rapid effort to build an AI-infrastructure portfolio beyond mobile processors. [4] A contemporary M&A analysis ranked Qualcomm’s Modular purchase as the next-largest non-biotech U.S. startup acquisition after Cursor, at about $4 billion. [2]\n\n**Caveat:** The available sources are inconsistent on the exact status and terms of the Qualcomm–Modular transaction: one June 22 report said Qualcomm was still nearing a deal and that final terms had not been reached, while another later analysis described it as an acquisition. [4][2]",
    "structured": null,
    "sources": [
      { "id": 1, "url": "https://pulse2.com/spacex-to-acquire-cursor-in-stock-deal-valuing-ai-coding-startup-at-60-billion/" },
      { "id": 2, "url": "https://news.crunchbase.com/ma/2026-mergers-acquisitions-record-cursor-spcx/" },
      { "id": 3, "url": "https://www.hindustantimes.com/business/nvidia-to-acquire-hugging-face-for-13-billion-why-the-ai-model-deal-matters-101788440128258.html" },
      { "id": 4, "url": "https://ca.finance.yahoo.com/news/qualcomm-nears-4b-deal-ai-221210867.html" }
    ],
    "grounding": []
  }
}
```

## 3. Read the result

In Python and TypeScript, `create_and_wait` / `createAndWait` already
returned this same envelope, so there is no separate call. Read
`run.output.text` and walk `run.output.sources` for the citation list:

<CodeGroup>
  ```python Python theme={null}
  print(run.output.text)
  for source in run.output.sources:
      print(f"[{source.id}] {source.url}")
  ```

  ```typescript TypeScript theme={null}
  console.log(run.output?.text);
  for (const source of run.output?.sources ?? []) {
    console.log(`[${source.id}] ${source.url}`);
  }
  ```
</CodeGroup>

```text Example output theme={null}
## Three most notable AI-company acquisitions announced in 2026

Assuming “notable” means a combination of deal size, strategic significance, and impact on the AI industry, the leading three are:

1. **SpaceX → Anysphere (Cursor) — $60 billion** (June 16). SpaceX announced an all-stock agreement to acquire Anysphere, the company behind the AI coding platform Cursor, at an implied $60 billion equity value. The transaction would make Anysphere a wholly owned SpaceX subsidiary and represents SpaceX’s major expansion from aerospace and satellite communications into AI software. [1] Crunchbase described it as the largest startup acquisition on record and said it accounted for roughly half of 2026 U.S. venture-backed startup M&A spending at that point. [2]

2. **Nvidia → Hugging Face — about $13 billion** (announced by September 3). Nvidia agreed to acquire Hugging Face, a major platform for AI models, datasets, and applications. It would be Nvidia’s largest outright acquisition, giving the chipmaker greater influence over AI-model distribution while expanding beyond chips into models, developers, and infrastructure. [3] Nvidia said Hugging Face would remain an open platform, with its more than 18 million developers retaining choice over models, cloud providers, and chips. [3]

3. **Qualcomm → Modular — approximately $4 billion** (June). Qualcomm pursued/acquired Modular, an AI software and chip company whose platform lets developers deploy models across different chips without rewriting code. The deal is notable because it forms part of Qualcomm’s rapid effort to build an AI-infrastructure portfolio beyond mobile processors. [4] A contemporary M&A analysis ranked Qualcomm’s Modular purchase as the next-largest non-biotech U.S. startup acquisition after Cursor, at about $4 billion. [2]

**Caveat:** The available sources are inconsistent on the exact status and terms of the Qualcomm–Modular transaction: one June 22 report said Qualcomm was still nearing a deal and that final terms had not been reached, while another later analysis described it as an acquisition. [4][2]

[1] https://pulse2.com/spacex-to-acquire-cursor-in-stock-deal-valuing-ai-coding-startup-at-60-billion/
[2] https://news.crunchbase.com/ma/2026-mergers-acquisitions-record-cursor-spcx/
[3] https://www.hindustantimes.com/business/nvidia-to-acquire-hugging-face-for-13-billion-why-the-ai-model-deal-matters-101788440128258.html
[4] https://ca.finance.yahoo.com/news/qualcomm-nears-4b-deal-ai-221210867.html
```

## Next steps

* [Structured output](/agent/guides/structured-output): requesting a JSON result instead of Markdown
* [List runs](/agent/guides/list-runs): paging this org's runs, newest first
* [Poll for completion](/agent/guides/poll-for-completion): managing the wait yourself
* [Cancel a run](/agent/guides/cancel-a-run): best-effort cancellation, and why it can lose the race to completion
* [Handle errors](/agent/guides/handle-errors): rejected requests versus failed runs
* [Reference](/agent/reference): endpoints, fields, limits and errors
* [Agent API Reference](/api-reference/agent/start-run): full REST request and response specification