Runs

Runs

Reference article: Part of the API reference. For runs in the app, see Workstream chat modes.

A run is one execution of work in a workstream, such as an agent working through a task, and often ends in a report. These endpoints list runs, check their status, and fetch their reports, so you can track work from your own dashboards or hand results to other systems.

Runs are visible only in workstreams the key can reach. A run in any other workstream behaves as if it doesn't exist. See Which workstreams a key can reach.

The Run object

{
  "id": "c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13",
  "object": "run",
  "workstream": "3f6c2a1e-8b4d-4e2f-9a7c-5d1b0e6f2a94",
  "status": "completed",
  "phase": null,
  "title": "Compare Q4 supplier price changes",
  "has_report": true,
  "created": 1758788700,
  "updated": 1758790022
}
Field Type Description
id string The run's ID.
object string Always run.
workstream string or null The ID of the workstream it ran in.
status string queued, pending, running, completed, failed, partial, or cancelled.
phase string or null The stage the run is in, when it reports one.
title string or null What the run set out to do.
has_report boolean true when the run has produced a report you can retrieve.
created integer When the run was created, in Unix seconds.
updated integer or null When it last changed, in Unix seconds.

List runs

Returns runs in workstreams the key can reach, newest first.

GET /v1/runs

Scope: runs:read

Parameter In Type Description
limit query integer, optional How many objects to return, 1–100. Default 20.
cursor query string, optional The next_cursor from the previous page. See Pagination.
workstream query string, optional Only runs in this workstream (id or slug).
status query string, optional Only runs with this status. One of the status values above.

::: code-group

curl "https://api.gonimbus.ai/v1/runs?workstream=q4-pricing-review&status=failed" \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const query = new URLSearchParams({ workstream: 'q4-pricing-review', status: 'failed' })
const response = await fetch(`https://api.gonimbus.ai/v1/runs?${query}`, {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const { data: runs } = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/runs",
    params={"workstream": "q4-pricing-review", "status": "failed"},
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
runs = response.json()["data"]

:::

Returns a list object of Run objects. A workstream the key can't reach fails with 404 resource_missing.

Retrieve a run

GET /v1/runs/{run}

Scope: runs:read

Parameter In Type Description
run path string The run's ID.

::: code-group

curl https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13 \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch('https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13', {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const run = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
run = response.json()

:::

Returns the Run object.

Retrieve a run's report {#retrieve-a-runs-report}

Returns the report a run produced. Until the run has one, this fails with 404 resource_missing; check has_report on the run first.

GET /v1/runs/{run}/report

Scope: runs:read

Parameter In Type Description
run path string The run's ID.

::: code-group

curl https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13/report \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const response = await fetch('https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13/report', {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_API_KEY}` },
})
const report = await response.json()

response = requests.get(
    "https://api.gonimbus.ai/v1/runs/c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13/report",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_API_KEY']}"},
)
report = response.json()

:::

{
  "object": "run_report",
  "run": "c1d7e4a9-3b8f-4c2e-9d6a-8f0b5e2c7a13",
  "title": "Q4 supplier price changes",
  "html": "<h2>Summary</h2><p>Three suppliers raised prices…</p>",
  "sections": [
    { "id": "summary", "title": "Summary" },
    { "id": "by-supplier", "title": "By supplier" }
  ],
  "generated": 1758790011
}
Field Type Description
object string Always run_report.
run string The ID of the run that produced it.
title string The report's title.
html string The report as sanitized HTML, ready to show in a page or email.
sections array The report's sections in order, each with an id and title. Use them to build a table of contents.
generated integer When the report was generated, in Unix seconds.

FAQ

How do I know when a run finishes?

Subscribe a webhook endpoint to run.completed and run.failed. If you poll instead, retrieve the run every few seconds or minutes, depending on how soon you need to know, and stop once its status is completed, failed, partial, or cancelled.

Can I start a run through the API?

You can run a loop now, which may start a run; the execution's run field tells you which. You can also ask the agent to do work in a workstream.

Is the report HTML safe to put in my page?

It's sanitized before it's returned. Still render it inside your own page's styles and content security rules, as you would any HTML from another system.

Why is a run in my organization missing from List runs?

It's in a workstream the key can't reach. An admin can grant the key that workstream on the Developers page; see Workstream access.

Can I get the report as a PDF?

Not through the API. It returns the report as sanitized HTML, which you can render or convert yourself.