---
title: "List jobs"
method: GET
path: "/jobs"
tags: ["API Endpoints"]
---

# List jobs

`GET /jobs`

List recent jobs with optional filtering by project or job type.

By default, jobs created within the last 7 days are returned. Use `created_after` and
`created_before` to customize the time range. The maximum lookback is 30 days.

Results are paginated. Use the `cursor` from the response `pagination.next_cursor` to
fetch subsequent pages.

Query parameters allow you to filter the results:
* Filter by `project_id` to see all jobs for a project
* Filter by `type` to see specific job types (import/project_media, agent)

## Query parameters

- `project_id` string, uuid
- `type` 'import/project_media' | 'agent'
- `cursor` string
- `limit` integer
- `created_after` string, date-time
- `created_before` string, date-time

## Response `200`

Jobs list retrieved successfully

- object
  - `data` JobStatus[], required
    - 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
              - …
          - 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
  - `pagination` object, required
    - `next_cursor` string — Cursor for the next page of results. Absent if no more results.

## Other responses

- `400` — Bad request - `project_id` is not a valid UUID
- `401` — Unauthorized - invalid or missing authentication token
- `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)