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

# Async runs

> How long-running audits start, report status, and return results.

[`gtm_audit`](/tools/gtm-audit) and [`org_audit`](/tools/org-audit) run a multi-step pipeline
that can take from tens of seconds to several minutes. Rather than blocking, they return a
**run id** immediately, and you poll for the result.

## Lifecycle

```mermaid theme={null}
flowchart LR
  A[gtm_audit / org_audit] -->|returns run id| B[run started]
  B --> C[get_run_status]
  C -->|status: running| C
  C -->|status: completed| D[full markdown result]
  C -->|status: failed| E[error message]
```

1. **Start** — call the audit tool. It returns markdown with a run id and the polling instruction.
2. **Poll** — call [`get_run_status`](/tools/get-run-status) with the matching `kind` and the `id`.
3. **Finish** — when `status` is `completed`, the poll returns the full result markdown. If it
   `failed`, the status includes an error message.

## Matching kind to tool

| Started by                      | Poll with `kind` |
| ------------------------------- | ---------------- |
| [`gtm_audit`](/tools/gtm-audit) | `"gtm-audit"`    |
| [`org_audit`](/tools/org-audit) | `"audit"`        |

Using the wrong `kind` for an id returns `not found`.

## Polling guidance

* Poll on an interval — every **10–20 seconds** is plenty. Avoid tight loops.
* Stop polling once status is `completed` or `failed`.
* Run ids are scoped to your organization. Polling an id that belongs to another org returns
  `not found`.

## Equivalent REST endpoint

The same status can be fetched over plain HTTP — handy for non-MCP clients:

```bash theme={null}
curl -s https://salesgraph.com/api/v1/runs/gtm-audit/<id> \
  -H "Authorization: Bearer $SALESGRAPH_API_KEY"
```

See the [REST API](/reference/rest-api) reference.