---
title: "Get job status"
method: GET
path: "/jobs/{job_id}"
tags: ["API Endpoints"]
---

# Get job status

`GET /jobs/{job_id}`

Retrieve the status of any job.

The response format varies based on job type and includes type-specific fields.

## Path parameters

- `job_id` string, uuid, required

## Response `200`

Job status retrieved successfully

- union — Status of an async job. The response structure varies based on the job type. Use the `job_type` field to determine which fields will be present.
  - ImportJobStatus — Status of an import job
    - `job_id` string, uuid, required — Unique identifier for the job
    - `job_type` 'import/project_media', required — Type of job
    - `job_state` 'queued' | 'running' | 'stopped' | 'cancelled', required — Current state of the job: - queued: Job is waiting to start - running: Job is actively processing - stopped: Job has finished (check result.status for outcome) - cancelled: Job was cancelled by user
    - `created_at` string, date-time, required — When the job was created
    - `stopped_at` string, date-time — When the job stopped (only present when job_state is stopped or cancelled)
    - `drive_id` string, uuid, required — The drive ID
    - `project_id` string, uuid, required — The project ID
    - `project_url` string, uri, required — URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.
    - `progress` object — Progress information for the workflow (only present when job_state is running)
      - `label` string, required — Human-readable label describing the current action
      - `percent` integer — Percentage of the workflow that has been completed
      - `last_update_at` string, date-time — When the progress was last updated
    - `result` union — Job result (only present when job_state is stopped)
      - ImportSuccessResult — Result when media was imported (fully or partially)
        - `status` 'success' | 'partial', required — - success: All media imported successfully - partial: Some media imported successfully, some failed
        - `media_status` object, required — Status of each media item in the import. Keys are the media reference IDs from the request.
        - `media_seconds_used` integer, required — Total media seconds consumed by this import
        - `created_compositions` object[] — Compositions created during import
          - `id` string
          - `name` string
      - ImportErrorResult — Result when job failed completely
        - `status` 'error', required — Job failed completely
        - `error_message` string, required — Human-readable error message
        - `error_code` string — Machine-readable error code
  - AgentJobStatus — Status of an Agent edit job
    - `job_id` string, uuid, required — Unique identifier for the job
    - `job_type` 'agent', required — Type of job
    - `job_state` 'queued' | 'running' | 'stopped' | 'cancelled', required — Current state of the job: - queued: Job is waiting to start - running: Job is actively processing - stopped: Job has finished (check result.status for outcome) - cancelled: Job was cancelled by user
    - `created_at` string, date-time, required — When the job was created
    - `stopped_at` string, date-time — When the job stopped (only present when job_state is stopped or cancelled)
    - `drive_id` string, uuid, required — The drive ID
    - `project_id` string, uuid, required — The project ID
    - `project_url` string, uri, required — URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.
    - `progress` object — Progress information for the workflow (only present when job_state is running)
      - `label` string, required — Human-readable label describing the current action
      - `percent` integer — Percentage of the workflow that has been completed
      - `last_update_at` string, date-time — When the progress was last updated
    - `result` union — Job result (only present when job_state is stopped)
      - AgentSuccessResult — Result when Agent edit completed successfully
        - `status` 'success', required — Indicates successful completion
        - `agent_response` string, required — AI response describing what was done
        - `project_changed` boolean, required — Whether the agent made modifications to the project
        - `media_seconds_used` integer — Media minutes (in seconds) consumed by this operation
        - `ai_credits_used` integer — AI credits consumed by this operation
        - `resolved_model` string — Model reported for this job: the canonical id for an explicit model or alias (e.g. `claude-opus-4.8` for `claude-opus`), or `auto` for an `auto` request. Present on jobs submitted via the public API after the model-aliases launch; older jobs may omit it.
        - `conversation_id` string, uuid — Conversation ID for this agent session. Pass this value as `conversation_id` in a subsequent [POST /jobs/agent](#operation/agentEditJob) request to continue the conversation.
      - AgentErrorResult — Result when Agent edit failed
        - `status` 'error', required — Indicates the job failed
        - `error_message` string, required — Human-readable error message
        - `error_code` string — Machine-readable error code
        - `resolved_model` string — Model reported for this job: the canonical id for an explicit model or alias, or `auto` for an `auto` request. Present on jobs submitted via the public API after the model-aliases launch; older jobs may omit it.
        - `conversation_id` string, uuid — Conversation ID for this agent session, if one was created before the error occurred.
  - PublishJobStatus — Status of a publish job
    - `job_id` string, uuid, required — Unique identifier for the job
    - `job_type` 'publish', required — Type of job
    - `job_state` 'queued' | 'running' | 'stopped' | 'cancelled', required — Current state of the job: - queued: Job is waiting to start - running: Job is actively processing - stopped: Job has finished (check result.status for outcome) - cancelled: Job was cancelled by user
    - `created_at` string, date-time, required — When the job was created
    - `stopped_at` string, date-time — When the job stopped (only present when job_state is stopped or cancelled)
    - `drive_id` string, uuid, required — The drive ID
    - `project_id` string, uuid, required — The project ID
    - `project_url` string, uri, required — URL to access the project in Descript web app. When a composition ID is available in the result, the URL includes a composition short ID suffix.
    - `progress` object — Progress information for the workflow (only present when job_state is running)
      - `label` string, required — Human-readable label describing the current action
      - `percent` integer — Percentage of the workflow that has been completed
      - `last_update_at` string, date-time — When the progress was last updated
      - `composition_id` string — Composition being published (present when known)
      - `share_url` string, uri — Share URL when available before the job completes
    - `result` union — Job result (only present when job_state is stopped)
      - PublishSuccessResult — Result when publish completed successfully
        - `status` 'success', required — Indicates successful completion
        - `composition_id` string, required — Identifier of the published composition
        - `share_url` string, uri, required — Public URL to view the published content
        - `media_type` 'Video' | 'Audio' — The media type the composition was actually published as. For an audio-only composition published with the default Video request, this is Audio.
        - `download_url` string, uri — Time-limited signed URL to download the original published media file. Present when the job completed successfully and signing succeeded.
        - `download_url_expires_at` string, date-time — ISO 8601 time when download_url expires (if download_url is set)
      - PublishErrorResult — Result when publish failed
        - `status` 'error', required — Indicates the publish job failed
        - `error_message` string, required — Human-readable error message

## Other responses

- `401` — Unauthorized - invalid or missing authentication token
- `403` — Forbidden - user does not have access to this job
- `404` — Job not found
- `429` — Too many requests - rate limit exceeded. Use the `Retry-After` header to determine when to retry.

---

[API](https://skmtc.dev/descriptapi/apis/descript-api.md) · [All operations](https://skmtc.dev/descriptapi/apis/descript-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/descriptapi/descript-api/revisions/04c0005aef70/schema)