Playground endpoints

GET /api/v1/projects/{project_id}/playground/replays

List replays

The project’s replays, newest first; trace_id and span_id narrow to one source.

Parameter	In	Type	Required	Notes
project_id	path	string (uuid)	yes
trace_id	query	string or null	no	max length 64
span_id	query	string or null	no	max length 64
limit	query	integer	no	min 1, max 200 Default 50.
cursor	query	string or null	no	max length 512

Status	Description	Body
200	Successful Response	application/json: Page_ReplaySummaryOut_
422	Validation Error	application/json: HTTPValidationError

POST /api/v1/projects/{project_id}/playground/replays

Replay a stored request

Send the span’s stored request once more with one of the organization’s credentials of the same provider, never streamed, n = 1, at most 4096 output tokens.

404 for a span outside the project or a credential outside the organization; 409 NOT_CONFIGURED without the gateway runtime, CREDENTIALS_KEYS or a replay budget; 422 REPLAY_* when the span cannot be replayed as it was; 409 REPLAY_BUDGET_EXCEEDED (with spent_usd, reserved_usd, budget_usd and month_start) when the month’s budget cannot take the call; 429 RATE_LIMITED after 30 playground runs a minute per user. A provider failure or a project budget block is the result’s error, not an HTTP error.

Parameter	In	Type	Required	Notes
project_id	path	string (uuid)	yes
Idempotency-Key	header	string or null	no	Makes a retry of this request safe: it runs once, then is replayed. min length 1, max length 128, pattern ^[\x21-\x7e]+$

Request body (application/json, required): ReplayIn

Status	Description	Body
200	Successful Response	application/json: ReplayOut
422	Validation Error	application/json: HTTPValidationError

GET /api/v1/projects/{project_id}/playground/replays/budget

Read the replay budget

The project’s replay budget for the current UTC month: REPLAY_MONTHLY_BUDGET_USD, what settled replays cost, what running ones hold, and what is left.

Parameter	In	Type	Required	Notes
project_id	path	string (uuid)	yes

Status	Description	Body
200	Successful Response	application/json: ReplayBudgetOut
422	Validation Error	application/json: HTTPValidationError

POST /api/v1/projects/{project_id}/playground/runs

Run prompts in the playground

Run 1 to 3 configurations at once and answer with one result each, in order.

A configuration that fails (a provider error, a missing variable) has its error and does not affect the others; a project budget that blocks a call is error = "BUDGET_EXCEEDED". Responses are not streamed, so ttft_ms is null. 404 for a credential outside the organization or a prompt version outside the project; 409 NOT_CONFIGURED without the gateway runtime or CREDENTIALS_KEYS; 429 RATE_LIMITED after 30 runs a minute per user.

Parameter	In	Type	Required	Notes
project_id	path	string (uuid)	yes
Idempotency-Key	header	string or null	no	Makes a retry of this request safe: it runs once, then is replayed. min length 1, max length 128, pattern ^[\x21-\x7e]+$

Request body (application/json, required): PlaygroundRunIn

Status	Description	Body
200	Successful Response	application/json: PlaygroundRunOut
422	Validation Error	application/json: HTTPValidationError

GET /api/v1/projects/{project_id}/traces/{trace_id}/spans/{span_id}/replay-source

Read what a replay of a span would send

Classify the span without calling a provider: its fidelity, surface, the credential family it needs and the stored request, or the refusal and its reason; plus its last ten replays. 404 when the span is not in the project.

Parameter	In	Type	Required	Notes
project_id	path	string (uuid)	yes
trace_id	path	string	yes
span_id	path	string	yes

Status	Description	Body
200	Successful Response	application/json: ReplaySourceOut
422	Validation Error	application/json: HTTPValidationError