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

# Check playbook run status

> Poll a playbook run started by `run_playbook`, using the `job_id` it returned.

<Info>
  **Tool** `run_playbook_status` · **Behavior** Read-only
</Info>

Poll a playbook run started by `run_playbook`, using the `job_id` it returned. While `status` is `running` or `pending`, poll again; when `succeeded`, `result` holds the check results.

## Input parameters

<ParamField body="job_id" type="string" required>
  The `job_id` returned by the executor tool.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Job identifier. Pass it to the matching `*_status` tool to poll.
</ResponseField>

<ResponseField name="status" type="'pending' | 'running' | 'succeeded' | 'failed' | 'canceled'">
  `succeeded` means `result` is populated; `running`/`pending` means poll again; `failed`/`canceled` are terminal.
</ResponseField>

<ResponseField name="result" type="object | null">
  Typed result when `status` is `succeeded`; `null` until then.

  <Expandable title="properties">
    <ResponseField name="playbookTitle" type="string" />

    <ResponseField name="totalChecks" type="number" />

    <ResponseField name="results" type="object[]">
      <Expandable title="properties">
        <ResponseField name="checkId" type="string (uuid)" />

        <ResponseField name="checkTitle" type="string" />

        <ResponseField name="evaluationResult" type="string">
          Evaluation outcome. One of `Pass`, `Flag`, `Fallback`, or `Error`.
        </ResponseField>

        <ResponseField name="documentPosition" type="number | null">
          Position in the document where the matched language was found, or null if not anchored.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="summary" type="object">
      <Expandable title="properties">
        <ResponseField name="flags" type="number" />

        <ResponseField name="fallbacks" type="number" />

        <ResponseField name="passes" type="number" />

        <ResponseField name="errors" type="number" />
      </Expandable>
    </ResponseField>

    <ResponseField name="documents" type="object[]">
      Redlined documents produced from the review's suggested revisions, applied as tracked changes. Present only when a single DOCX file was reviewed under a user-scoped key and at least one revision applied. The original file is preserved; each entry exposes a new `file_id` and a signed download URL.

      <Expandable title="properties">
        <ResponseField name="file_id" type="string (uuid)">
          The new uploaded file ID for the produced document. Use it with `POST /chat/completions` `file_ids` to apply further edits to this version. Download via `signed_url` for the finished file.
        </ResponseField>

        <ResponseField name="original_file_id" type="string (uuid)">
          The `file_id` the changes were applied to (edits only). The original file is preserved unchanged. Omitted for newly generated documents.
        </ResponseField>

        <ResponseField name="filename" type="string">
          Filename of the produced document (edits are prefixed with `edited_`).
        </ResponseField>

        <ResponseField name="original_filename" type="string">
          Filename of the source file the changes were applied to (edits only). Omitted for newly generated documents.
        </ResponseField>

        <ResponseField name="signed_url" type="string (uri)">
          Time-limited direct download URL (no login required). Valid for 7 days from job completion. Download promptly; the URL is not re-minted, so re-fetching the job after expiry returns the same expired URL. For a link you intend to store or email, use `download_url` instead.
        </ResponseField>

        <ResponseField name="download_url" type="string (uri)">
          Permanent, login-gated download link for the produced document. Unlike `signed_url` it never expires: it points at a GC AI web page that mints a fresh download for a signed-in user with access to the file, and redirects to GC AI login otherwise. Use this for links you store or email. The produced document inherits the source document's access, so it opens for whoever can already see the source: a document uploaded to the organization is org-visible, one in a project is visible to that project's members, and one in personal files stays private to the uploader. Recipients still need a GC AI login.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status_tool" type="string">
  The exact tool to call to poll this job. Call it yourself with `job_id`; do not ask the user to poll.
</ResponseField>

<ResponseField name="poll_after_seconds" type="number | null">
  While `status` is `pending`/`running`, wait this many seconds, then call `status_tool` with `job_id`. `null` once the job is terminal.
</ResponseField>

<ResponseField name="hint" type="string">
  Plain-language next step. Follow it before responding.
</ResponseField>