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

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

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



## OpenAPI

````yaml /openapi.json get /v1/jobs/{job_id}
openapi: 3.1.0
info:
  title: Universal Document AI API
  description: AI-powered document editing with multi-tenant organization support
  version: 2.0.0
servers: []
security: []
paths:
  /v1/jobs/{job_id}:
    get:
      tags:
        - v1
        - mcp
        - jobs
      summary: >-
        Get the status, partial results, and any pending changes for an async
        chat job.
      description: >-
        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.
      operationId: get_job
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    JobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier. Use this to poll for status updates.
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: Organization that owns this job (null for user jobs).
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User that owns this job (null for organization jobs).
        session_id:
          type: string
          title: Session Id
          description: Session associated with this job.
        job_type:
          type: string
          title: Job Type
          description: 'Type of job: ''chat'' or ''attachment_processing''.'
        status:
          type: string
          title: Status
          description: >-
            Current status: 'pending', 'in_progress', 'awaiting_approval',
            'completed', 'failed', or 'cancelled'.
        created_at:
          type: string
          title: Created At
          description: ISO 8601 timestamp when the job was created.
        updated_at:
          type: string
          title: Updated At
          description: ISO 8601 timestamp of the last status change.
        progress:
          type: integer
          title: Progress
          description: Progress percentage (0-100).
        result:
          anyOf:
            - $ref: '#/components/schemas/JobResult'
            - type: 'null'
          description: >-
            Job output. Present when status is 'completed'. Contains AI response
            and document changes for chat jobs.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message. Present when status is 'failed'.
        metadata:
          anyOf:
            - $ref: '#/components/schemas/JobMetadata'
            - type: 'null'
          description: >-
            Job metadata and context. Contains pending_changes when status is
            'awaiting_approval'.
      type: object
      required:
        - job_id
        - session_id
        - job_type
        - status
        - created_at
        - updated_at
        - progress
      title: JobResponse
      description: Status and details of an async job.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    JobResult:
      properties:
        response:
          anyOf:
            - type: string
            - type: 'null'
          title: Response
          description: AI response text (chat jobs).
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: Session identifier (chat jobs).
        document_changes:
          anyOf:
            - $ref: '#/components/schemas/DocumentChanges'
            - type: 'null'
          description: Document modifications (chat jobs).
        usage:
          anyOf:
            - $ref: '#/components/schemas/UsageInfo'
            - type: 'null'
          description: Usage tracking data (chat jobs).
        attachment_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Attachment Id
          description: Processed attachment identifier (attachment processing jobs).
      additionalProperties: true
      type: object
      title: JobResult
      description: Job result data. Structure depends on job type.
    JobMetadata:
      properties:
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Uploaded filename (attachment processing jobs).
        file_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: File Size
          description: File size in bytes (attachment processing jobs).
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
          description: MIME type of uploaded file (attachment processing jobs).
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Original user message (chat jobs).
        document_html_provided:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Document Html Provided
          description: Whether document HTML was included in the request (chat jobs).
        pending_changes:
          anyOf:
            - items:
                $ref: '#/components/schemas/PendingChange'
              type: array
            - type: 'null'
          title: Pending Changes
          description: >-
            Proposed changes awaiting approval. Present when job status is
            'awaiting_approval'.
        intermediate_responses:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Intermediate Responses
          description: >-
            Progress updates during processing. Each item has: type, content,
            sequence, timestamp.
      additionalProperties: true
      type: object
      title: JobMetadata
      description: Job metadata. Contents vary by job type.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    DocumentChanges:
      properties:
        updated_html:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated Html
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Version Id
          description: Document version identifier. Changes on every modification.
        changes_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Changes Summary
          description: Human-readable summary of what was changed.
        requires_approval:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Requires Approval
          description: >-
            If true, changes need review via the approve endpoint before being
            applied.
        pending_changes:
          anyOf:
            - items:
                $ref: '#/components/schemas/PendingChange'
              type: array
            - type: 'null'
          title: Pending Changes
          description: >-
            Proposed changes awaiting approval. Present when requires_approval
            is true.
        changes:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Changes
          description: History of individual changes applied during this request.
        chunk_diffs:
          anyOf:
            - items:
                $ref: '#/components/schemas/PendingChange'
              type: array
            - type: 'null'
          title: Chunk Diffs
          description: >-
            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.
      additionalProperties: true
      type: object
      title: DocumentChanges
      description: Document modifications produced by the AI assistant.
    UsageInfo:
      properties:
        monthly_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Monthly Used
          description: Total operations used this billing cycle.
        monthly_limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Monthly Limit
          description: Maximum operations allowed per cycle. -1 means unlimited.
        monthly_remaining:
          anyOf:
            - type: integer
            - type: 'null'
          title: Monthly Remaining
          description: Operations remaining this cycle. -1 means unlimited.
        was_billable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Was Billable
          description: Whether this request counted as a billable operation.
        ops_charged:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ops Charged
          description: >-
            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:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Quota Exhausted
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Subscription Tier
          description: 'Current subscription tier: ''free'', ''plus'', ''pro'', or ''enterprise''.'
        bucket_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Bucket Used
          description: >-
            Which bucket this operation drew from: 'tier' or 'promo'. Null for
            non-billable ops.
        redemption_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Redemption Id
          description: Redemption grant this op drew from, when bucket_used is 'promo'.
        promotions:
          anyOf:
            - items:
                $ref: '#/components/schemas/ActivePromotionInfo'
              type: array
            - type: 'null'
          title: Promotions
          description: >-
            User's currently-active promotion grants, ordered by oldest-expiring
            first.
      additionalProperties: true
      type: object
      title: UsageInfo
      description: Operation usage data for the current billing cycle.
    PendingChange:
      properties:
        change_id:
          type: string
          title: Change Id
          description: Unique identifier for this proposed change.
        operation:
          type: string
          title: Operation
          description: 'Type of change: ''edit'', ''create'', or ''delete''.'
        chunk_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Chunk Id
          description: Target document section ID being modified or deleted.
        document_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Id
          description: >-
            Identifier of the document (tab) this change applies to — lets
            multi-document integrators attribute each section diff to the right
            document.
        old_html:
          anyOf:
            - type: string
            - type: 'null'
          title: Old Html
          description: Previous HTML content of the section (for updates).
        new_html:
          anyOf:
            - type: string
            - type: 'null'
          title: New Html
          description: Proposed new HTML content (for updates and creates).
        ai_explanation:
          anyOf:
            - type: string
            - type: 'null'
          title: Ai Explanation
          description: AI-generated explanation of why this change was proposed.
      additionalProperties: true
      type: object
      required:
        - change_id
        - operation
      title: PendingChange
      description: A proposed document change awaiting user approval.
    ActivePromotionInfo:
      properties:
        redemption_id:
          type: string
          title: Redemption Id
          description: Unique identifier for this promotion grant.
        name:
          type: string
          title: Name
          description: Human-friendly promotion name (e.g., 'YC SUS India 2026 cohort').
        ops_remaining:
          type: integer
          title: Ops Remaining
          description: Operations still available in this promotion bucket.
        ops_granted:
          type: integer
          title: Ops Granted
          description: Total operations originally granted by this redemption.
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Expires At
          description: ISO 8601 expiry timestamp. Null if the credits never expire.
      additionalProperties: true
      type: object
      required:
        - redemption_id
        - name
        - ops_remaining
        - ops_granted
      title: ActivePromotionInfo
      description: >-
        A single active (drawable) promotion belonging to the authenticated
        user.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````