---
title: "Retrieve a run"
method: GET
path: "/api/v3/runs/{runId}"
tags: ["run"]
---

# Retrieve a run

`GET /api/v3/runs/{runId}`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v3/runs/{runId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v3/runs/:runId/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve information about a run, including its status, payload, output, and attempts. If you authenticate with a Public API key, we will omit the payload and output fields for security reasons.

## Response `200`

Successful request

- RetrieveRunResponse
  - `id` string, required: The unique ID of the run, prefixed with `run_`
  - `status` 'PENDING_VERSION' | 'DELAYED' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE', required: The status of the run
  - `taskIdentifier` string, required: The identifier of the task that was run
  - `version` string: The version of the worker that executed the run
  - `idempotencyKey` string: The idempotency key used to prevent creating duplicate runs, if provided
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `isTest` boolean: Whether the run is a test run or not
  - `startedAt` string, date-time: The time the run started
  - `finishedAt` string, date-time: The time the run finished
  - `delayedUntil` string, date-time: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
  - `ttl` union: The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
    - string
    - number
  - `expiredAt` string, date-time: If the run had a TTL and that time has passed, when the run "expired".
  - `tags` string[]: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
  - `metadata` object: The metadata of the run. See [Metadata](/runs/metadata) for more information.
  - `costInCents` number: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
  - `baseCostInCents` number: The invocation cost of the run in cents. This cost does not apply to DEV runs.
  - `durationMs` number: The duration of compute (so far) in milliseconds. This does not include waits.
  - `depth` integer: The depth of the run in the task run hierarchy. The root run has a depth of 0.
  - `batchId` string: The ID of the batch that this run belongs to
  - `triggerFunction` 'trigger' | 'triggerAndWait' | 'batchTrigger' | 'batchTriggerAndWait': The name of the function that triggered the run
  - `payload` object: The payload that was sent to the task. Will be omitted if the request was made with a Public API key
  - `payloadPresignedUrl` string: The presigned URL to download the payload. Will only be included if the payload is too large to be included in the response. Expires in 5 minutes.
  - `output` object: The output of the run. Will be omitted if the request was made with a Public API key
  - `outputPresignedUrl` string: The presigned URL to download the output. Will only be included if the output is too large to be included in the response. Expires in 5 minutes.
  - `relatedRuns` object
    - `root` CommonRunObject
      - `id` string, required: The unique ID of the run, prefixed with `run_`
      - `status` 'PENDING_VERSION' | 'DELAYED' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE', required: The status of the run
      - `taskIdentifier` string, required: The identifier of the task that was run
      - `version` string: The version of the worker that executed the run
      - `idempotencyKey` string: The idempotency key used to prevent creating duplicate runs, if provided
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `isTest` boolean: Whether the run is a test run or not
      - `startedAt` string, date-time: The time the run started
      - `finishedAt` string, date-time: The time the run finished
      - `delayedUntil` string, date-time: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
      - `ttl` union: The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
        - string
        - number
      - `expiredAt` string, date-time: If the run had a TTL and that time has passed, when the run "expired".
      - `tags` string[]: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
      - `metadata` object: The metadata of the run. See [Metadata](/runs/metadata) for more information.
      - `costInCents` number: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
      - `baseCostInCents` number: The invocation cost of the run in cents. This cost does not apply to DEV runs.
      - `durationMs` number: The duration of compute (so far) in milliseconds. This does not include waits.
      - `depth` integer: The depth of the run in the task run hierarchy. The root run has a depth of 0.
      - `batchId` string: The ID of the batch that this run belongs to
      - `triggerFunction` 'trigger' | 'triggerAndWait' | 'batchTrigger' | 'batchTriggerAndWait': The name of the function that triggered the run
    - `parent` CommonRunObject
      - `id` string, required: The unique ID of the run, prefixed with `run_`
      - `status` 'PENDING_VERSION' | 'DELAYED' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE', required: The status of the run
      - `taskIdentifier` string, required: The identifier of the task that was run
      - `version` string: The version of the worker that executed the run
      - `idempotencyKey` string: The idempotency key used to prevent creating duplicate runs, if provided
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `isTest` boolean: Whether the run is a test run or not
      - `startedAt` string, date-time: The time the run started
      - `finishedAt` string, date-time: The time the run finished
      - `delayedUntil` string, date-time: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
      - `ttl` union: The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
        - string
        - number
      - `expiredAt` string, date-time: If the run had a TTL and that time has passed, when the run "expired".
      - `tags` string[]: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
      - `metadata` object: The metadata of the run. See [Metadata](/runs/metadata) for more information.
      - `costInCents` number: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
      - `baseCostInCents` number: The invocation cost of the run in cents. This cost does not apply to DEV runs.
      - `durationMs` number: The duration of compute (so far) in milliseconds. This does not include waits.
      - `depth` integer: The depth of the run in the task run hierarchy. The root run has a depth of 0.
      - `batchId` string: The ID of the batch that this run belongs to
      - `triggerFunction` 'trigger' | 'triggerAndWait' | 'batchTrigger' | 'batchTriggerAndWait': The name of the function that triggered the run
    - `children` CommonRunObject[]: The immediate children of the run. Will be omitted if the run has no children
      - `id` string, required: The unique ID of the run, prefixed with `run_`
      - `status` 'PENDING_VERSION' | 'DELAYED' | 'QUEUED' | 'EXECUTING' | 'REATTEMPTING' | 'FROZEN' | 'COMPLETED' | 'CANCELED' | 'FAILED' | 'CRASHED' | 'INTERRUPTED' | 'SYSTEM_FAILURE', required: The status of the run
      - `taskIdentifier` string, required: The identifier of the task that was run
      - `version` string: The version of the worker that executed the run
      - `idempotencyKey` string: The idempotency key used to prevent creating duplicate runs, if provided
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `isTest` boolean: Whether the run is a test run or not
      - `startedAt` string, date-time: The time the run started
      - `finishedAt` string, date-time: The time the run finished
      - `delayedUntil` string, date-time: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
      - `ttl` union: The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1).
        - string
        - number
      - `expiredAt` string, date-time: If the run had a TTL and that time has passed, when the run "expired".
      - `tags` string[]: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
      - `metadata` object: The metadata of the run. See [Metadata](/runs/metadata) for more information.
      - `costInCents` number: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
      - `baseCostInCents` number: The invocation cost of the run in cents. This cost does not apply to DEV runs.
      - `durationMs` number: The duration of compute (so far) in milliseconds. This does not include waits.
      - `depth` integer: The depth of the run in the task run hierarchy. The root run has a depth of 0.
      - `batchId` string: The ID of the batch that this run belongs to
      - `triggerFunction` 'trigger' | 'triggerAndWait' | 'batchTrigger' | 'batchTriggerAndWait': The name of the function that triggered the run
  - `schedule` object: The schedule that triggered the run. Will be omitted if the run was not triggered by a schedule
    - `id` string, required: The unique ID of the schedule, prefixed with `sched_`
    - `externalId` string: The external ID of the schedule. Can be anything that is useful to you (e.g., user ID, org ID, etc.)
    - `deduplicationKey` string: The deduplication key used to prevent creating duplicate schedules
    - `generator` object, required
      - `type` 'CRON'
      - `expression` string: The cron expression used to generate the schedule
      - `description` string: The description of the generator in plain english
  - `attempts` object[], required
    - `id` string, required: The unique ID of the attempt, prefixed with `attempt_`
    - `status` 'PENDING' | 'EXECUTING' | 'PAUSED' | 'COMPLETED' | 'FAILED' | 'CANCELED', required
    - `error` SerializedError
      - `message` string, required
      - `name` string
      - `stackTrace` string
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `startedAt` string, date-time
    - `completedAt` string, date-time

## Other responses

- `400`: Invalid request
- `401`: Unauthorized request
- `404`: Resource not found

## Changes

- **2025-09-10** `b3bb08191152`: 1 info
  - endpoint added
- **2025-09-08** `f88f9449b635`: 1 breaking
  - api path removed without deprecation
- **2025-03-21** `7e4036741e50`: 4 warning, 4 info
  - added the new `PENDING_VERSION` enum value to the `allOf[#/components/schemas/CommonRunObject]/status` response property for the response status `200`
  - added the new `PENDING_VERSION` enum value to the `allOf[subschema #2]/relatedRuns/children/items/status` response property for the response status `200`
  - added the new `PENDING_VERSION` enum value to the `allOf[subschema #2]/relatedRuns/parent/status` response property for the response status `200`
  - added the new `PENDING_VERSION` enum value to the `allOf[subschema #2]/relatedRuns/root/status` response property for the response status `200`
  - …4 more
- **2024-09-26** `9691a7335fb7`: 4 info
  - added the optional property `allOf[#/components/schemas/CommonRunObject]/metadata` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/relatedRuns/children/items/metadata` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/relatedRuns/parent/metadata` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/relatedRuns/root/metadata` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v3/runs/:runId/get.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)