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

# Retrieve a run

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

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

---

[API](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api.md) · [All operations](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/winsenlabs/trigger-dev-v3-rest-api/revisions/5a645d85c8c4/schema)