Skip to content

Add token usage and timing fields to get-request docs #228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jped merged 1 commit into from
Feb 27, 2026
Merged

Add token usage and timing fields to get-request docs #228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 179 additions & 33 deletions openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1034,7 +1034,11 @@
"description": "Whether this column contributes to built-in score averaging (defaults to false)"
}
},
"required": ["column_type", "name", "configuration"]
"required": [
"column_type",
"name",
"configuration"
]
}
},
"score_configuration": {
Expand All @@ -1047,11 +1051,16 @@
},
"code_language": {
"type": "string",
"enum": ["PYTHON", "JAVASCRIPT"],
"enum": [
"PYTHON",
"JAVASCRIPT"
],
"description": "Language of the code (defaults to PYTHON)"
}
},
"required": ["code"]
"required": [
"code"
]
}
},
"required": [
Expand Down Expand Up @@ -1103,13 +1112,27 @@
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"report_id": { "type": "integer" },
"column_type": { "type": "string" },
"name": { "type": "string" },
"position": { "type": "integer" },
"is_part_of_score": { "type": "boolean" },
"configuration": { "type": "object" }
"id": {
"type": "integer"
},
"report_id": {
"type": "integer"
},
"column_type": {
"type": "string"
},
"name": {
"type": "string"
},
"position": {
"type": "integer"
},
"is_part_of_score": {
"type": "boolean"
},
"configuration": {
"type": "object"
}
}
}
}
Expand Down Expand Up @@ -1232,11 +1255,33 @@
"type": "string",
"description": "The type of evaluation or transformation this column performs. Must be one of the supported column types.",
"enum": [
"ABSOLUTE_NUMERIC_DISTANCE", "AI_DATA_EXTRACTION", "ASSERT_VALID", "CONVERSATION_SIMULATOR",
"COALESCE", "CODE_EXECUTION", "COMBINE_COLUMNS", "COMPARE", "CONTAINS", "COSINE_SIMILARITY",
"COUNT", "ENDPOINT", "MCP", "HUMAN", "JSON_PATH", "LLM_ASSERTION", "MATH_OPERATOR",
"MIN_MAX", "PARSE_VALUE", "APPLY_DIFF", "PROMPT_TEMPLATE", "REGEX", "REGEX_EXTRACTION",
"VARIABLE", "XML_PATH", "WORKFLOW", "CODING_AGENT"
"ABSOLUTE_NUMERIC_DISTANCE",
"AI_DATA_EXTRACTION",
"ASSERT_VALID",
"CONVERSATION_SIMULATOR",
"COALESCE",
"CODE_EXECUTION",
"COMBINE_COLUMNS",
"COMPARE",
"CONTAINS",
"COSINE_SIMILARITY",
"COUNT",
"ENDPOINT",
"MCP",
"HUMAN",
"JSON_PATH",
"LLM_ASSERTION",
"MATH_OPERATOR",
"MIN_MAX",
"PARSE_VALUE",
"APPLY_DIFF",
"PROMPT_TEMPLATE",
"REGEX",
"REGEX_EXTRACTION",
"VARIABLE",
"XML_PATH",
"WORKFLOW",
"CODING_AGENT"
]
},
"name": {
Expand Down Expand Up @@ -2037,7 +2082,11 @@
"required": false,
"schema": {
"type": "string",
"enum": ["active", "deleted", "all"],
"enum": [
"active",
"deleted",
"all"
],
"default": "active"
},
"description": "Filter datasets by status: 'active' (default) returns only active datasets, 'deleted' returns only deleted/archived datasets, 'all' returns both"
Expand Down Expand Up @@ -2195,6 +2244,41 @@
"model": {
"type": "string",
"description": "The model name (e.g. gpt-4, claude-3-sonnet)."
},
"input_tokens": {
"type": "integer",
"nullable": true,
"description": "Number of input tokens used."
},
"output_tokens": {
"type": "integer",
"nullable": true,
"description": "Number of output tokens generated."
},
"tokens": {
"type": "integer",
"nullable": true,
"description": "Total token count (input + output)."
},
"price": {
"type": "number",
"nullable": true,
"description": "Cost of the request in USD."
},
"request_start_time": {
"type": "string",
"nullable": true,
"description": "ISO 8601 timestamp of when the request started."
},
"request_end_time": {
"type": "string",
"nullable": true,
"description": "ISO 8601 timestamp of when the request ended."
},
"latency_ms": {
"type": "number",
"nullable": true,
"description": "Request latency in milliseconds, derived from start and end times."
}
}
}
Expand Down Expand Up @@ -2286,7 +2370,11 @@
"required": false,
"schema": {
"type": "string",
"enum": ["active", "deleted", "all"],
"enum": [
"active",
"deleted",
"all"
],
"default": "active"
},
"description": "Filter evaluations by status: 'active' (default) returns only active evaluations, 'deleted' returns only deleted/archived evaluations, 'all' returns both"
Expand Down Expand Up @@ -2800,7 +2888,11 @@
"name": "status",
"schema": {
"type": "string",
"enum": ["active", "deleted", "all"],
"enum": [
"active",
"deleted",
"all"
],
"default": "active",
"title": "Status"
},
Expand Down Expand Up @@ -4291,7 +4383,12 @@
"description": "Whether this node is an output node."
}
},
"required": ["name", "node_type", "configuration", "is_output_node"]
"required": [
"name",
"node_type",
"configuration",
"is_output_node"
]
},
"EdgeConditional": {
"type": "object",
Expand All @@ -4303,7 +4400,18 @@
},
"operator": {
"type": "string",
"enum": ["=", "!=", "<", ">", "<=", ">=", "in", "not_in", "is_null", "is_not_null"],
"enum": [
"=",
"!=",
"<",
">",
"<=",
">=",
"in",
"not_in",
"is_null",
"is_not_null"
],
"description": "Comparison operator."
},
"left_config": {
Expand All @@ -4315,7 +4423,12 @@
"description": "Right side of comparison. Can be static_value or source."
}
},
"required": ["position", "operator", "left_config", "right_config"]
"required": [
"position",
"operator",
"left_config",
"right_config"
]
},
"Edge": {
"type": "object",
Expand All @@ -4341,7 +4454,12 @@
"description": "At least one conditional."
}
},
"required": ["source_node_name", "target_node_name", "is_and", "conditionals"]
"required": [
"source_node_name",
"target_node_name",
"is_and",
"conditionals"
]
},
"CreateWorkflow": {
"type": "object",
Expand Down Expand Up @@ -4404,7 +4522,9 @@
"description": "Labels to attach to this version."
}
},
"required": ["nodes"],
"required": [
"nodes"
],
"description": "Request body for creating a new workflow or workflow version."
},
"NodeUpdate": {
Expand Down Expand Up @@ -4453,8 +4573,12 @@
"type": "object",
"additionalProperties": {
"oneOf": [
{ "$ref": "#/components/schemas/NodeUpdate" },
{ "type": "null" }
{
"$ref": "#/components/schemas/NodeUpdate"
},
{
"type": "null"
}
]
},
"nullable": true,
Expand Down Expand Up @@ -4528,10 +4652,18 @@
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"node_type": { "type": "string" },
"is_output_node": { "type": "boolean" }
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"node_type": {
"type": "string"
},
"is_output_node": {
"type": "boolean"
}
}
},
"description": "Summary of nodes in the workflow."
Expand All @@ -4544,7 +4676,13 @@
"description": "Required input variables for the workflow."
}
},
"required": ["success", "workflow_id", "workflow_name", "workflow_version_id", "version_number"],
"required": [
"success",
"workflow_id",
"workflow_name",
"workflow_version_id",
"version_number"
],
"description": "Response after creating or patching a workflow."
},
"ErrorResponse": {
Expand Down Expand Up @@ -6663,7 +6801,11 @@
},
"status": {
"type": "string",
"enum": ["SUCCESS", "WARNING", "ERROR"],
"enum": [
"SUCCESS",
"WARNING",
"ERROR"
],
"default": "SUCCESS",
"title": "Status",
"description": "Request status.\n\n| Value | Description |\n|-------|-------------|\n| `SUCCESS` | Request completed successfully (default) |\n| `WARNING` | Request succeeded but had issues (e.g., retries, degraded response) |\n| `ERROR` | Request failed |"
Expand Down Expand Up @@ -6728,7 +6870,11 @@
},
"status": {
"type": "string",
"enum": ["SUCCESS", "WARNING", "ERROR"],
"enum": [
"SUCCESS",
"WARNING",
"ERROR"
],
"title": "Status",
"description": "Request status indicating success, warning, or error."
},
Expand Down Expand Up @@ -7465,4 +7611,4 @@
}
}
}
}
}
14 changes: 11 additions & 3 deletions reference/get-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
---
title: "Get Request"
openapi: "GET /api/public/v2/request/{request_id}"
description: "Retrieve a request's payload as a prompt blueprint."
description: "Retrieve a request's payload as a prompt blueprint, along with token usage and timing data."
---

Retrieve the full payload of a logged request by its ID, returned as a [prompt blueprint](/running-requests/prompt-blueprints). This is useful for:

- **Request replay**: Re-run a request with the same input and parameters
- **Debugging**: Inspect the exact prompt and model configuration used
- **Dataset creation**: Extract request data for use in evaluations
- **Cost analysis**: Review token usage and pricing for individual requests

The response includes the prompt blueprint (input messages, model configuration, and parameters) along with the provider and model used.
The response includes the prompt blueprint (input messages, model configuration, and parameters) along with token counts and timing data.

### Authentication

Expand Down Expand Up @@ -49,7 +50,14 @@ curl -H "X-API-KEY: your_api_key" \
},
"request_id": 12345,
"provider": "openai",
"model": "gpt-4"
"model": "gpt-4",
"input_tokens": 12,
"output_tokens": 25,
"tokens": 37,
"price": 0.00123,
"request_start_time": "2024-04-03T20:57:25",
"request_end_time": "2024-04-03T20:57:26",
"latency_ms": 1000.0
}
```

Expand Down