---
title: "Get the status, partial results, and any pending changes for an async chat job."
method: GET
path: "/v1/jobs/{job_id}"
tags: ["v1", "mcp", "jobs"]
---

# Get the status, partial results, and any pending changes for an async chat job.

`GET /v1/jobs/{job_id}`

## Request

- Base URL: `https://api.superdocs.app`
- URL: `https://api.superdocs.app/v1/jobs/{job_id}`
- Auth: HTTP bearer

Returns the job's current state (pending, in_progress, awaiting_approval, completed, failed, or cancelled), intermediate AI responses streamed during execution, the final document HTML once complete, and any pending changes awaiting user approval (with chunk IDs and proposed HTML diffs in metadata.pending_changes). Poll this after chat_async to track progress and retrieve results. When status is awaiting_approval, call POST /v1/chat/{session_id}/approve to approve or deny each pending change. Headless/MCP clients get the same typed progress events the web SSE stream delivers via metadata.intermediate_responses (e.g. documents_changed, continue_prompt, model_fallback, proposed_change_batch); cross-session document updates from OTHER sessions are reported separately by polling GET /v1/sessions/{session_id}/doc-events.

## Path parameters

- `job_id` string, required

## Query parameters

- `compact` boolean: When true, omit the heavy result body + streamed intermediate events from the response (status/progress/ids/timestamps/pending-change ids remain). Recommended for AI agents polling a large-document job: poll compact while it runs, then fetch once non-compact when status is completed to retrieve the final HTML.

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- JobResponse: Status and details of an async job.
  - `job_id` string, required: Unique job identifier. Use this to poll for status updates.
  - `organization_id` string, nullable: Organization that owns this job (null for user jobs).
  - `user_id` string, nullable: User that owns this job (null for organization jobs).
  - `session_id` string, required: Session associated with this job.
  - `job_type` string, required: Type of job: 'chat' or 'attachment_processing'.
  - `status` string, required: Current status: 'pending', 'in_progress', 'awaiting_approval', 'completed', 'failed', or 'cancelled'.
  - `created_at` string, required: ISO 8601 timestamp when the job was created.
  - `updated_at` string, required: ISO 8601 timestamp of the last status change.
  - `progress` integer, required: Progress percentage (0-100).
  - `result` JobResult: Job result data. Structure depends on job type.
    - `response` string, nullable: AI response text (chat jobs).
    - `session_id` string, nullable: Session identifier (chat jobs).
    - `document_changes` DocumentChanges: Document modifications produced by the AI assistant.
      - `updated_html` string, nullable: Full updated document HTML with data-chunk-id attributes. Apply this to your editor to sync the document. Present in 'full' response mode (default); null in 'compact' mode.
      - `version_id` string, nullable: Document version identifier. Changes on every modification.
      - `changes_summary` string, nullable: Human-readable summary of what was changed.
      - `requires_approval` boolean, nullable: If true, changes need review via the approve endpoint before being applied.
      - `pending_changes` PendingChange[], nullable: Proposed changes awaiting approval. Present when requires_approval is true.
        - `change_id` string, required: Unique identifier for this proposed change.
        - `operation` string, required: Type of change: 'edit', 'create', or 'delete'.
        - `chunk_id` string, nullable: Target document section ID being modified or deleted.
        - `document_id` string, nullable: Identifier of the document (tab) this change applies to — lets multi-document integrators attribute each section diff to the right document.
        - `old_html` string, nullable: Previous HTML content of the section (for updates).
        - `new_html` string, nullable: Proposed new HTML content (for updates and creates).
        - `ai_explanation` string, nullable: AI-generated explanation of why this change was proposed.
      - `changes` object[], nullable: History of individual changes applied during this request.
      - `chunk_diffs` PendingChange[], nullable: Per-section before/after content for changes that were applied this turn. Present in 'compact' response mode (when updated_html is null) so the agent can verify what was modified without paying token cost for the full document. Same shape as pending_changes.
        - `change_id` string, required: Unique identifier for this proposed change.
        - `operation` string, required: Type of change: 'edit', 'create', or 'delete'.
        - `chunk_id` string, nullable: Target document section ID being modified or deleted.
        - `document_id` string, nullable: Identifier of the document (tab) this change applies to — lets multi-document integrators attribute each section diff to the right document.
        - `old_html` string, nullable: Previous HTML content of the section (for updates).
        - `new_html` string, nullable: Proposed new HTML content (for updates and creates).
        - `ai_explanation` string, nullable: AI-generated explanation of why this change was proposed.
      - `concurrent_merges` object[], nullable: Present ONLY when this request's edit collided with a concurrent edit: another session/chat committed a different change to the same section(s) while this request was processing, and the two were merged server-side. One entry per affected document: {document_id, durable_document_id, version, conflicting_sections}. When present, updated_html reflects the merged COMMITTED state — it may differ from the text this response describes; review the affected sections and re-apply anything that was superseded. Absent (null) on every non-conflicting request, including concurrent edits to DIFFERENT sections (those merge cleanly with no data loss and no notice).
    - `usage` UsageInfo: Operation usage data for the current billing cycle.
      - `monthly_used` integer, nullable: Total operations used this billing cycle.
      - `monthly_limit` integer, nullable: Maximum operations allowed per cycle. -1 means unlimited.
      - `monthly_remaining` integer, nullable: Operations remaining this cycle. -1 means unlimited.
      - `was_billable` boolean, nullable: Whether this request counted as a billable operation.
      - `ops_charged` integer, nullable: How many operations this request billed. A large multi-section edit can bill more than one (one per 25 sections edited), so monthly_used can increase by more than 1 between responses.
      - `quota_exhausted` boolean, nullable: True when you have reached your plan's operation limit with no remaining balance — the current request still completes, but further billable requests pause until you upgrade or your billing cycle resets.
      - `subscription_tier` string, nullable: Current subscription tier: 'free', 'plus', 'pro', or 'enterprise'.
      - `bucket_used` string, nullable: Which bucket this operation drew from: 'tier' or 'promo'. Null for non-billable ops.
      - `redemption_id` string, nullable: Redemption grant this op drew from, when bucket_used is 'promo'.
      - `promotions` ActivePromotionInfo[], nullable: User's currently-active promotion grants, ordered by oldest-expiring first.
        - `redemption_id` string, required: Unique identifier for this promotion grant.
        - `name` string, required: Human-friendly promotion name (e.g., 'YC SUS India 2026 cohort').
        - `ops_remaining` integer, required: Operations still available in this promotion bucket.
        - `ops_granted` integer, required: Total operations originally granted by this redemption.
        - `expires_at` string, nullable: ISO 8601 expiry timestamp. Null if the credits never expire.
    - `attachment_id` string, nullable: Processed attachment identifier (attachment processing jobs).
  - `error` string, nullable: Error message. Present when status is 'failed'.
  - `metadata` JobMetadata: Job metadata. Contents vary by job type.
    - `filename` string, nullable: Uploaded filename (attachment processing jobs).
    - `file_size` integer, nullable: File size in bytes (attachment processing jobs).
    - `content_type` string, nullable: MIME type of uploaded file (attachment processing jobs).
    - `message` string, nullable: Original user message (chat jobs).
    - `document_html_provided` boolean, nullable: Whether document HTML was included in the request (chat jobs).
    - `pending_changes` PendingChange[], nullable: Proposed changes awaiting approval. Present when job status is 'awaiting_approval'.
      - `change_id` string, required: Unique identifier for this proposed change.
      - `operation` string, required: Type of change: 'edit', 'create', or 'delete'.
      - `chunk_id` string, nullable: Target document section ID being modified or deleted.
      - `document_id` string, nullable: Identifier of the document (tab) this change applies to — lets multi-document integrators attribute each section diff to the right document.
      - `old_html` string, nullable: Previous HTML content of the section (for updates).
      - `new_html` string, nullable: Proposed new HTML content (for updates and creates).
      - `ai_explanation` string, nullable: AI-generated explanation of why this change was proposed.
    - `intermediate_responses` object[], nullable: Progress updates during processing. Each item has: type, content, sequence, timestamp.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/superdocs/apis/universal-document-ai-api.md) · [All operations](https://skmtc.dev/superdocs/apis/universal-document-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superdocs/apis/universal-document-ai-api/revisions/37d03122940b?raw)