> ## Documentation Index > Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve run trace > 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. Returns the OpenTelemetry trace subtree for the run you request. The response `trace.rootSpan` is that run's span — not necessarily the trace-wide root — with its descendant spans nested under `children`. For a child or nested run inside a large trace, this endpoint scopes the tree to that run so you still get a useful subtree even when the full trace has more spans than the platform can return in one response. For a finished run, spans that finish more than 7 days after the run are returned in their last recorded state. ## Page large traces The tree response stops at a size limit. To get every span of a large trace, page it: send `page[size]` (1,000–10,000) on the first request, then pass each response's `pagination.next` back as `page[after]` until it's absent. ```ts Your backend code theme={"theme":"css-variables"} const spans = []; let after: string | undefined; do { const query = new URLSearchParams({ "page[size]": "10000" }); if (after) query.set("page[after]", after); const response = await fetch(`https://api.trigger.dev/api/v1/runs/run_1234/trace?${query}`, { headers: { Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}` }, }); const page = await response.json(); spans.push(...page.data); after = page.pagination.next; } while (after); ``` * Paging works for runs at the root of their trace. Other runs return `400`; request their trace without page parameters. * Pages contain flat spans without events or properties. Rebuild the tree from `parentId`, or use `assembleRunTracePages` from `@trigger.dev/core/v3`, which also marks unfinished spans under a cancelled or failed parent the way the tree response does. * A span can appear on two pages, once in progress and once finished. Keep the finished one. * `pagination.truncated` means some spans or records were left out: paging stopped early (for example while an emergency span limit is in place), or a span had more records than one read allows. * Send `Accept-Encoding: gzip` when you call the endpoint directly. ## OpenAPI ````yaml v3-openapi GET /api/v1/runs/{runId}/trace openapi: 3.1.0 info: title: Trigger.dev v3 REST API description: >- The REST API lets you trigger and manage runs on Trigger.dev. You can trigger a run, get the status of a run, and get the results of a run. version: 2024-04 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.trigger.dev description: Trigger.dev API security: [] paths: /api/v1/runs/{runId}/trace: parameters: - $ref: '#/components/parameters/runId' get: tags: - runs summary: Retrieve run trace description: >- 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. operationId: get_run_trace_v1 parameters: - in: query name: page[size] required: false schema: type: integer minimum: 1 description: >- Turns on paging. Spans per page; values are clamped to 1,000–10,000. Defaults to 10,000 when only `page[after]` is sent. - in: query name: page[after] required: false schema: type: string description: >- Turns on paging. The `pagination.next` cursor from the previous page, passed back unchanged. Omit it for the first page. responses: '200': description: >- Successful request. Without page parameters, the nested trace tree. With them, one page of flat spans. content: application/json: schema: oneOf: - type: object title: Trace tree properties: trace: type: object properties: traceId: type: string description: The OTel trace ID. rootSpan: allOf: - $ref: '#/components/schemas/SpanDetailedSummary' description: >- The requested run's span, with nested descendant spans as `children`. Not necessarily the trace-wide root span. - type: object title: Trace page properties: data: type: array description: >- Spans on this page, in start-time order. A span can appear on two pages (in progress, then finished); keep the finished one. items: type: object properties: id: type: string parentId: type: string runId: type: string message: type: string startTime: type: string format: date-time duration: type: number description: Duration in nanoseconds. isError: type: boolean isPartial: type: boolean description: Still in progress. isCancelled: type: boolean level: type: string enum: - TRACE - DEBUG - LOG - INFO - WARN - ERROR attemptNumber: type: number attemptFailures: type: array description: >- Failed-attempt records on this page. A span still in progress under a failed attempt of its run counts as errored. items: type: object properties: spanId: type: string attemptNumber: type: number runId: type: string pagination: type: object properties: next: type: string description: Cursor for the next page. Absent on the last page. truncated: type: boolean description: >- 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. '400': description: >- Invalid page parameters, or page parameters on a run that isn't at the root of its trace content: application/json: schema: type: object properties: error: type: string '401': description: Unauthorized request content: application/json: schema: type: object properties: error: type: string enum: - Invalid or Missing API key '404': description: Resource not found content: application/json: schema: type: object properties: error: type: string enum: - Run not found - Trace not found '501': description: Paging isn't supported by this deployment's trace store content: application/json: schema: type: object properties: error: type: string '503': description: >- The trace store is temporarily unavailable, or paging is temporarily limited to the first page. Back off and retry later (see `Retry-After`). content: application/json: schema: type: object properties: error: type: string security: - secretKey: [] x-codeSamples: - lang: typescript label: Trace tree source: >- const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/trace", { headers: { Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`, }, }); const { trace } = await response.json(); - lang: typescript label: Paged source: |- const spans = []; let after; do { const query = new URLSearchParams({ "page[size]": "10000" }); if (after) query.set("page[after]", after); const response = await fetch( `https://api.trigger.dev/api/v1/runs/run_1234/trace?${query}`, { headers: { Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}` } } ); const page = await response.json(); spans.push(...page.data); after = page.pagination.next; } while (after); components: parameters: runId: in: path name: runId required: true schema: type: string description: > The ID of an run, starts with `run_`. The run ID will be returned when you trigger a run on a task. example: run_1234 schemas: SpanDetailedSummary: type: object properties: id: type: string description: The span ID. parentId: type: string nullable: true description: The parent span ID, if any. runId: type: string description: The run ID this span belongs to. data: type: object properties: message: type: string description: The span message. taskSlug: type: string description: The task identifier, if applicable. startTime: type: string format: date-time description: The start time of the span. duration: type: number description: The duration of the span in nanoseconds. isError: type: boolean isPartial: type: boolean isCancelled: type: boolean level: type: string enum: - TRACE - DEBUG - LOG - INFO - WARN - ERROR attemptNumber: type: number nullable: true properties: type: object description: Arbitrary OTel attributes attached to the span. events: type: array description: >- Span events (e.g. exceptions, cancellations) that occurred during this span. items: type: object properties: name: type: string description: >- The event name (e.g. "exception", "cancellation", "attempt_failed"). time: type: string format: date-time description: The time the event occurred. properties: type: object description: Event-specific properties. children: type: array description: >- Nested child spans. Each child has the same structure as the parent span. items: $ref: '#/components/schemas/SpanDetailedSummary' securitySchemes: secretKey: type: http scheme: bearer description: > Use a named environment API key. It starts with `tr_dev_sk_`, `tr_prod_sk_`, `tr_stg_sk_`, etc. Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration. Our TypeScript SDK will default to using the value of the `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function. ```typescript import { configure } from "@trigger.dev/sdk"; configure({ accessToken: "tr_dev_sk_1234" }); ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.