Get a trace - PlungeAI

/v1/traces/{id}

Authorization: send Authorization: Bearer $PLUNGE_API_KEY; X-API-Key: <ozk_ key> is accepted as an alternative.

Spans are written from a queue and can lag a run that just finished. An unknown id also answers 200 with empty arrays.

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer ozk_…. ozk_ platform API key (Authorization: Bearer ozk_…)

Path parameters

idstringrequired

Response

Trace

application/json

trace_idstring

cost_usdnumber | null

The execution row’s priced cost (workflow_executions.cost_usd); null until workflow-cost has priced the run

cost_statusenum<string> | null

Available options: priced, partial, unpriced, null

spansSpan[]

Show child attributes

idintegerrequired

trace_idstringrequired

workflow_idstringrequired

task_idstring | null

tsintegerrequired

typestringrequired

request_received|task_dispatched|task_completed|workflow_result|…

agentstring | null

statusstring | null

duration_msinteger | null

payload_refstring | null

R2 key when large, else null

payload_inlinestring | null

guard-scanned, <=1KB

gateway_requestsGatewayRequest[]

Show child attributes

idstringrequired

trace_idstring | null

planestringrequired

routestringrequired

user_idstring | null

statusintegerrequired

upstreamstring | null

duration_msinteger | null

cost_usdnumber | null

created_atintegerrequired

unauthorized — missing, invalid or revoked ozk_ key

Error code: unauthorizedfrom code

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

not_found — the id is unknown, or the trace belongs to another key (the same answer for both). Spans and request logs land asynchronously: retry in a few seconds after a run

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

connectobject

On a 424 connection_required / credential_required: where the missing connection is made.

Show child attributes

providerstring

methodenum<string>

Available options: oauth, api_key, wallet

linkstring

Example: "POST /v1/connections/stripe/link"

import os import requests response = requests.get( "https://api.plungeai.com/v1/traces/{id}", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, ) if not response.ok: raise SystemExit(f"{response.status_code} {response.headers.get('X-Error-Code')}") print(response.json())

const response = await fetch('https://api.plungeai.com/v1/traces/{id}', { method: 'GET', headers: { Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`, }, }) if (!response.ok) throw new Error(`${response.status} ${response.headers.get('X-Error-Code')}`) console.log(await response.json())

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/v1/traces/{id}")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { System.out.println(response.statusCode() + " " + response.headers().firstValue("X-Error-Code").orElse("")); return; } System.out.println(response.body()); } }