--- title: "Get async job status" method: GET path: "/jobs/{id}" tags: ["Async Jobs"] --- # Get async job status `GET /jobs/{id}` ## Request - Base URL: `https://app.gc.ai/api/external/v1` - URL: `https://app.gc.ai/api/external/v1/jobs/{id}` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Poll an async API job created by endpoints like `POST /chat/completions`. Use the `job_id` returned by a `202 Accepted` response to check whether the job is still pending or has reached a terminal state. ## Path parameters - `id` string, uuid, required: The async job ID ## Query parameters - `wait` integer, nullable: Optional long-poll wait time in seconds. Use `0` for fire-and-forget behavior. If both `wait` and `Prefer: wait=...` are supplied, they must match. Values above 90 are clamped. ## Headers - `Prefer` string: Optional RFC 7240 wait preference, for example `wait=0`. If both this header and the `wait` query parameter are supplied, they must match. ## Response `200` Job found and currently in a terminal state - ChatCompletionResponse - `job_id` string, uuid, required: Async job identifier - `kind` 'chat/completions', required: Stable job kind for this endpoint - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'canceled', required: Current job status - `result` ChatCompletionResult, nullable, required: Completion payload when the job has succeeded - `result` string, required: The AI-generated response text - `chat_id` string, uuid, required: The chat ID. API chats stay out of chat history until you materialize them. Pass `materialize: true` on the request to surface the chat in the same call, or pass this ID to `POST /chat/{id}/materialize` afterwards. See [Chat Visibility](https://docs.gc.ai/api-reference/concepts/chat-visibility). - `chat_url` string, uri: Deep link that opens the chat in the GC AI web app. Present only when the request set `materialize: true` and the chat was surfaced, so its absence means the chat is still headless. - `documents` ApiDocument[]: 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`. - `file_id` string, uuid, required: 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. - `original_file_id` string, uuid: The `file_id` the changes were applied to (edits only). The original file is preserved unchanged. Omitted for newly generated documents. - `filename` string, required: Filename of the produced document (edits are prefixed with `edited_`). - `original_filename` string: Filename of the source file the changes were applied to (edits only). Omitted for newly generated documents. - `signed_url` string, uri, required: 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. - `download_url` string, uri, required: 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. - `emails` ApiEmail[]: 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. - `to` string, required: Recipient email address(es), comma-separated. May be an empty string when the prompt named no recipient; fill it in before sending. - `cc` string: CC recipient email address(es), comma-separated. - `bcc` string: BCC recipient email address(es), comma-separated. - `subject` string, required: Email subject line. Always present, inferred from context when the prompt did not specify one. - `body` string, required: Email body in markdown. - `plaintext_body` string, required: Email body with markdown stripped, for plain-text clients. - `diagrams` ApiDiagram[]: 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. - `title` string, required: A short descriptive title for the diagram. - `diagram_type` string, required: The semantic type of diagram, e.g. orgChart, dealStructure, workflow, timeline, sequence, entityRelationship, or general. - `mermaid` string, required: The diagram source as validated Mermaid syntax. Render it with any Mermaid-compatible renderer. - `judge_approved_steps` string[]: GC AI actions, by tool name, that the safety check approved during this completion. Present only when `auto_accept` was set and the check approved at least one step. - `skipped_steps` string[]: GC AI actions, by tool name, that needed a person to approve them and did not run. Present only when at least one step was skipped. - `error` object, nullable, required: Failure payload when the job has failed - `code` string, required - `message` string, required - `created_at` string, required: ISO 8601 creation timestamp - `completed_at` string, nullable, required: ISO 8601 completion timestamp, or null when not terminal ## Other responses - `202`: Job found but not yet complete - `400`: Invalid job ID, wait value, or conflicting wait controls - `401`: Missing or malformed API key - `403`: Invalid API key - `404`: Job not found - `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off. - `500`: Internal server error - `503`: Service temporarily unavailable --- [API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)