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

# Get Spread

> Poll a financial spreading run's status and artifacts

Retrieve a spreading run: its lifecycle status, per-document progress, and — once complete — its report and spreadsheet artifacts. Poll this endpoint while a run is in flight, or subscribe to the [spread webhooks](/api-reference/webhooks/webhook-events) instead.

## Authentication

Requires the `x-api-key` header with a valid workspace API key.

## Path Parameters

<ParamField path="spreadId" type="string" required>
  The run id returned by [Create Spread](/api-reference/spreads/create-spread).
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="spread" type="object">
  The run.

  <Expandable title="spread">
    <ResponseField name="id" type="string">
      The run id.
    </ResponseField>

    <ResponseField name="status" type="string">
      The lifecycle status: `IN_PROGRESS`, `COMPLETE`, or `FAILED`.
    </ResponseField>

    <ResponseField name="error" type="string | null">
      The failure message when `status` is `FAILED`, otherwise `null`.
    </ResponseField>

    <ResponseField name="leadId" type="string | null">
      The lead the run belongs to.
    </ResponseField>

    <ResponseField name="documents" type="array">
      The input documents, each with `id`, `filename`, `status` (`PROCESSING`,
      `EXTRACTED`, `SKIPPED`, or `FAILED`), and
      `error`. `id` is the document's id in your workspace — the same id the
      [document endpoints](/api-reference/documents/get-document) use — or
      `null` if the document has since been deleted.
    </ResponseField>

    <ResponseField name="artifacts" type="array">
      The report and spreadsheet, each with `id`, `type`
      (`REPORT` or `SPREADSHEET`), and `title`. Populated whenever `status` is
      `COMPLETE`. A regenerating run keeps its previous artifacts until the new
      ones replace them on completion.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      When the run was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      When the run last changed.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

<ResponseField name="404" type="error">
  No spread with this id exists in your workspace.
</ResponseField>

<RequestExample>
  ```javascript Node.js theme={null}
  const options = {
    method: "GET",
    headers: { "x-api-key": "<your-api-key>" },
  };

  fetch(
    "https://api-v2.getomni.ai/api/v1/spreads/9f1e2d3c-4b5a-6789-0abc-def012345678",
    options,
  )
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
  ```

  ```python Python theme={null}
  import requests

  url = "https://api-v2.getomni.ai/api/v1/spreads/9f1e2d3c-4b5a-6789-0abc-def012345678"
  headers = {"x-api-key": "<your-api-key>"}

  response = requests.request("GET", url, headers=headers)
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api-v2.getomni.ai/api/v1/spreads/9f1e2d3c-4b5a-6789-0abc-def012345678 \
    --header 'x-api-key: <your-api-key>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "spread": {
      "id": "9f1e2d3c-4b5a-6789-0abc-def012345678",
      "status": "COMPLETE",
      "error": null,
      "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
      "documents": [
        { "id": "doc-a", "filename": "2023-tax-return.pdf", "status": "EXTRACTED", "error": null },
        { "id": "doc-b", "filename": "2023-financials.pdf", "status": "EXTRACTED", "error": null }
      ],
      "artifacts": [
        { "id": "art-report", "type": "REPORT", "title": "Financial Spread - Pacific Coast Container Haulers" },
        { "id": "art-sheet", "type": "SPREADSHEET", "title": "Financial Spread - Pacific Coast Container Haulers (Excel)" }
      ],
      "createdAt": "2026-07-23T18:04:00.000Z",
      "updatedAt": "2026-07-23T18:08:40.000Z"
    }
  }
  ```
</ResponseExample>