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

# Retrieve run trace

`GET /api/v1/runs/{runId}/trace`

## Request

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

Returns the OTel trace subtree for the requested run — the run's span as `rootSpan`, its ancestor chain, and its descendant spans. For child or nested runs in a large trace, this is scoped to that run rather than the trace-wide root. Pass `page[size]` or `page[after]` to page the trace as flat spans instead; paging works for runs at the root of their trace.

## Query parameters

- `page[size]` integer
- `page[after]` string

## Response `200`

Successful request. Without page parameters, the nested trace tree. With them, one page of flat spans.

- union
  - object
    - `trace` object
      - `traceId` string: The OTel trace ID.
      - `rootSpan` SpanDetailedSummary
        - `id` string: The span ID.
        - `parentId` string, nullable: The parent span ID, if any.
        - `runId` string: The run ID this span belongs to.
        - `data` object
          - `message` string: The span message.
          - `taskSlug` string: The task identifier, if applicable.
          - `startTime` string, date-time: The start time of the span.
          - `duration` number: The duration of the span in nanoseconds.
          - `isError` boolean
          - `isPartial` boolean
          - `isCancelled` boolean
          - `level` 'TRACE' | 'DEBUG' | 'LOG' | 'INFO' | 'WARN' | 'ERROR'
          - `attemptNumber` number, nullable
          - `properties` object: Arbitrary OTel attributes attached to the span.
          - `events` object[]: Span events (e.g. exceptions, cancellations) that occurred during this span.
            - `name` string: The event name (e.g. "exception", "cancellation", "attempt_failed").
            - `time` string, date-time: The time the event occurred.
            - `properties` object: Event-specific properties.
        - `children` SpanDetailedSummary[]: Nested child spans. Each child has the same structure as the parent span.
  - object
    - `data` object[]: Spans on this page, in start-time order. A span can appear on two pages (in progress, then finished); keep the finished one.
      - `id` string
      - `parentId` string
      - `runId` string
      - `message` string
      - `startTime` string, date-time
      - `duration` number: Duration in nanoseconds.
      - `isError` boolean
      - `isPartial` boolean: Still in progress.
      - `isCancelled` boolean
      - `level` 'TRACE' | 'DEBUG' | 'LOG' | 'INFO' | 'WARN' | 'ERROR'
      - `attemptNumber` number
    - `attemptFailures` object[]: Failed-attempt records on this page. A span still in progress under a failed attempt of its run counts as errored.
      - `spanId` string
      - `attemptNumber` number
      - `runId` string
    - `pagination` object
      - `next` string: Cursor for the next page. Absent on the last page.
      - `truncated` boolean: Some spans or records were left out. Either paging stopped early (for example while an emergency span limit is in place) or a span had more records than one read allows; `next` is still returned in that case.

## Other responses

- `400`: Invalid page parameters, or page parameters on a run that isn't at the root of its trace
- `401`: Unauthorized request
- `404`: Resource not found
- `501`: Paging isn't supported by this deployment's trace store
- `503`: The trace store is temporarily unavailable, or paging is temporarily limited to the first page. Back off and retry later (see `Retry-After`).

## Changes

- **2026-10-09** `20d6a8f28ae9`: 2 breaking, 1 warning, 5 info
  - added `subschema #1: Trace tree, subschema #2: Trace page` to the response body `oneOf` list for the response status `200`
  - the response's body type changed from `object` to no type for status `200`
  - removed the optional property `trace` from the response with the `200` status
  - added the new optional `query` request parameter `page[after]`
  - …4 more
- **2026-06-30** `e82ac1cca8d1`: 1 breaking, 5 warning, 1 info
  - the `trace/rootSpan` response's property type changed from `object` to no type for status `200`
  - removed the optional property `trace/rootSpan/children` from the response with the `200` status
  - removed the optional property `trace/rootSpan/data` from the response with the `200` status
  - removed the optional property `trace/rootSpan/id` from the response with the `200` status
  - …3 more
- **2026-02-24** `6ec7a0ed3a5e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/runs/:runId/trace/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)