> ## 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 chat completion status

> Poll a chat completion started by `ask_gcai`, using the `job_id` it returned.

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

Poll a chat completion started by `ask_gcai`, using the `job_id` it returned. While `status` is `running` or `pending`, poll again; when `succeeded`, `result` holds the answer.

## 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="result" type="string">
      The AI-generated response text
    </ResponseField>

    <ResponseField name="chat_id" type="string (uuid)">
      The chat ID. API chats stay out of chat history until you materialize them. Pass this ID to `POST /chat/{id}/materialize` to surface the chat. See [Chat Visibility](/api-reference/concepts/chat-visibility).
    </ResponseField>

    <ResponseField name="documents" type="object[]">
      Documents produced during this completion: either edits of an attached file (the document editing tool) or newly generated files (the document or slide generation tools). Present only when at least one document was produced. Each entry exposes a new `file_id` and a signed download URL; edits also reference the preserved original via `original_file_id`.

      <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>

    <ResponseField name="emails" type="object[]">
      Email drafts produced during this completion by the email drafting tool. Present only when at least one email was drafted. Each entry is a structured draft (`to`, `subject`, `body`, …) ready to send via your own mail client or provider.

      <Expandable title="properties">
        <ResponseField name="to" type="string">
          Recipient email address(es), comma-separated. May be an empty string when the prompt named no recipient; fill it in before sending.
        </ResponseField>

        <ResponseField name="cc" type="string">
          CC recipient email address(es), comma-separated.
        </ResponseField>

        <ResponseField name="bcc" type="string">
          BCC recipient email address(es), comma-separated.
        </ResponseField>

        <ResponseField name="subject" type="string">
          Email subject line. Always present, inferred from context when the prompt did not specify one.
        </ResponseField>

        <ResponseField name="body" type="string">
          Email body in markdown.
        </ResponseField>

        <ResponseField name="plaintext_body" type="string">
          Email body with markdown stripped, for plain-text clients.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="diagrams" type="object[]">
      Diagrams produced during this completion by the diagram tool. Present only when at least one diagram was produced. Each entry exposes validated Mermaid source (`mermaid`) you can render with any Mermaid-compatible renderer.

      <Expandable title="properties">
        <ResponseField name="title" type="string">
          A short descriptive title for the diagram.
        </ResponseField>

        <ResponseField name="diagram_type" type="string">
          The semantic type of diagram, e.g. orgChart, dealStructure, workflow, timeline, sequence, entityRelationship, or general.
        </ResponseField>

        <ResponseField name="mermaid" type="string">
          The diagram source as validated Mermaid syntax. Render it with any Mermaid-compatible renderer.
        </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>