Request logs
Package: agentrouter.insights.v1 Service: RequestLogsService
Endpoints
Query request logs
What it does: Retrieves request logs with filtering and pagination.
Request fields:
| Field | Required | Description |
|---|---|---|
user_id | no | Filter by user ID |
api_key_id | no | Filter by API key ID |
model_name | no | Filter by model name (e.g., "claude-3-opus", "gpt-4") |
status | no | Filter by status (e.g., "success", "error", "timeout") |
status_code | no | Filter by HTTP status code |
start_time | no | Start of time range (inclusive) |
end_time | no | End of time range (exclusive) |
min_duration_ms | no | Minimum duration in milliseconds |
max_duration_ms | no | Maximum duration in milliseconds |
page_size | no | Page size (default: 50, max: 1000) |
page_token | no | Page token for pagination |
order_by | no | Order by field (default: "timestamp") Valid values: "timestamp", "duration_ms", "input_tokens", "output_tokens" |
order_direction | no | Order direction: "asc" or "desc" (default: "desc") |
Response fields:
| Field | Required | Description |
|---|---|---|
logs | no | List of request logs matching the query |
next_page_token | no | Token for retrieving the next page (empty if no more pages) |
total_count | no | Total count of matching logs (may be approximate for large datasets) |
{"signatures":{"go":"func (x *RequestLogsClient) QueryRequestLogs(ctx context.Context, req *insightsv1.QueryRequestLogsRequest) (*insightsv1.QueryRequestLogsResponse, error)","python":"query_request_logs(req: request_logs_pb2.QueryRequestLogsRequest) -\u003e QueryRequestLogsResponse","typescript":"queryRequestLogs(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.QueryRequestLogsRequestSchema \u003e): Promise\u003cQueryRequestLogsResponse\u003e","cli":"tare api request-logs query","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tinsightsv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/insights/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026insightsv1.QueryRequestLogsRequest{}\n\n\tresp, err := client.RequestLogs().QueryRequestLogs(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/requestlogs/queryrequestlogs\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.insights.v1 import request_logs_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = request_logs_pb2.QueryRequestLogsRequest()\ntry:\n result = client.request_logs.query_request_logs(req)\n print(result)\nexcept Exception as err:\n print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n# agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n baseUrl: process.env.AGENTROUTER_BASE_URL,\n apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n const result = await client.requestLogs.queryRequestLogs(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"requestlogs\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^20.0.0\",\n \"typescript\": \"^5.4.0\"\n }\n}\n"},{"name":"tsconfig.json","content":"{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true\n }\n}\n"}]},"cli":"tare api request-logs query","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"GET","httpPath":"/v1/request-logs","slug":"query-request-logs"}Get request log
What it does: Retrieves a single request log by request ID.
Request fields:
| Field | Required | Description |
|---|---|---|
request_id | no | Request identifier |
Response fields:
| Field | Required | Description |
|---|---|---|
id | no | Unique log identifier |
timestamp | no | Timestamp when the request was received |
user_id | no | User ID who made the request |
api_key_id | no | API key information UUID of the API key that authenticated the request. |
api_key_prefix | no | Leading visible characters of the key (e.g. "sk-..."), for display. |
api_key_hash | no | Hash of the API key used to look it up without storing the secret. |
api_key_address | no | On-chain/account address the API key is bound to. |
api_key_name | no | Human-readable label assigned to the API key. |
model_name | no | Model name used for the request |
input_tokens | no | Token usage Number of prompt/input tokens consumed by the request. |
output_tokens | no | Number of completion/output tokens generated in the response. |
input_tokens_cost_microdollar | no | Cost information (in microdollars and decimal) Input-token cost in microdollars (1e-6 USD), after fee. |
input_tokens_cost | no | undocumented |
input_tokens_cost_before_fee | no | Input-token cost before the platform fee/markup is applied. Decimal string. |
output_tokens_cost_microdollar | no | Output-token cost in microdollars (1e-6 USD), after fee. |
output_tokens_cost | no | undocumented |
output_tokens_cost_before_fee | no | Output-token cost before the platform fee/markup is applied. Decimal string. |
status | no | Request/Response status Logical outcome of the request (e.g. "success", "error", "timeout"). |
status_code | no | HTTP status code returned to the client. |
request_headers | no | Request metadata Captured request headers as a JSON object. |
request_body | no | Captured request payload as a JSON object. |
response_headers | no | Response metadata Captured response headers as a JSON object. |
response_body | no | undocumented |
response_body_raw | no | undocumented |
llm_parameters | no | LLM parameters used |
upstream_duration_ms | no | Timing information |
duration_ms | no | undocumented |
request_id | no | Request identifier |
created_at | no | Record creation timestamp |
storage_location | no | Object storage information (for Parquet-based storage) |
storage_row_index | no | undocumented |
storage_batch_id | no | undocumented |
use_object_storage | no | undocumented |
cached_input_tokens | no | Cache token breakdown. Input tokens served from the prompt cache (cache reads), billed at the cached rate. |
cached_input_tokens_cost | no | undocumented |
cached_input_tokens_cost_before_fee | no | Cached-input cost before the platform fee/markup is applied. Decimal string. |
cache_creation_input_tokens | no | Input tokens written to the prompt cache (cache-creation writes). |
cache_creation_input_tokens_cost | no | undocumented |
cache_creation_input_tokens_cost_before_fee | no | Cache-creation cost before the platform fee/markup is applied. Decimal string. |
{"signatures":{"go":"func (x *RequestLogsClient) GetRequestLog(ctx context.Context, req *insightsv1.GetRequestLogRequest) (*insightsv1.RequestLog, error)","python":"get_request_log(req: request_logs_pb2.GetRequestLogRequest) -\u003e RequestLog","typescript":"getRequestLog(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.GetRequestLogRequestSchema \u003e): Promise\u003cRequestLog\u003e","cli":"tare api request-logs get","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tinsightsv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/insights/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026insightsv1.GetRequestLogRequest{}\n\n\tresp, err := client.RequestLogs().GetRequestLog(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/requestlogs/getrequestlog\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.insights.v1 import request_logs_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = request_logs_pb2.GetRequestLogRequest()\ntry:\n result = client.request_logs.get_request_log(req)\n print(result)\nexcept Exception as err:\n print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n# agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n baseUrl: process.env.AGENTROUTER_BASE_URL,\n apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n const result = await client.requestLogs.getRequestLog(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"requestlogs\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^20.0.0\",\n \"typescript\": \"^5.4.0\"\n }\n}\n"},{"name":"tsconfig.json","content":"{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true\n }\n}\n"}]},"cli":"tare api request-logs get","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"GET","httpPath":"/v1/request-logs/{request_id}","slug":"get-request-log"}Get request log stats
What it does: Returns aggregated statistics for request logs.
Request fields:
| Field | Required | Description |
|---|---|---|
user_id | no | Filter by user ID |
model_name | no | Filter by model name |
start_time | no | Start of time range (inclusive) |
end_time | no | End of time range (exclusive) |
group_by | no | Group by dimension Valid values: "model", "user", "api_key", "status", "hour", "day" |
metric | no | Metric to calculate Valid values: "count", "tokens", "cost", "latency", "errors" |
Response fields:
| Field | Required | Description |
|---|---|---|
stats | no | Statistics grouped by the requested dimension |
total_count | no | Total counts across all groups Total number of requests across all groups. |
total_input_tokens | no | Sum of input tokens across all groups. |
total_output_tokens | no | Sum of output tokens across all groups. |
total_cost | no | undocumented |
avg_duration_ms | no | Mean request duration in milliseconds across all groups. |
error_count | no | Total number of error requests across all groups. |
{"signatures":{"go":"func (x *RequestLogsClient) GetRequestLogStats(ctx context.Context, req *insightsv1.GetRequestLogStatsRequest) (*insightsv1.RequestLogStatsResponse, error)","python":"get_request_log_stats(req: request_logs_pb2.GetRequestLogStatsRequest) -\u003e RequestLogStatsResponse","typescript":"getRequestLogStats(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.GetRequestLogStatsRequestSchema \u003e): Promise\u003cRequestLogStatsResponse\u003e","cli":"tare api request-logs request-log-stats get","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs/stats\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":{"files":[{"name":"main.go","content":"// Command example is a runnable example for the AgentRouter Go SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then `go run .`.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\tagentrouter \"github.com/tetrateio/agentrouter-go\"\n\tinsightsv1 \"github.com/tetrateio/agentrouter-go/genapi/api/tars/insights/v1\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tclient, err := agentrouter.New(ctx,\n\t\tagentrouter.WithBaseURL(os.Getenv(\"AGENTROUTER_BASE_URL\")),\n\t\tagentrouter.WithAPIKey(os.Getenv(\"AGENTROUTER_API_KEY\")),\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"client: %v\", err)\n\t}\n\n\t// Populate the request fields -- see the \"Request fields\" table above for\n\t// the available fields and which are required.\n\treq := \u0026insightsv1.GetRequestLogStatsRequest{}\n\n\tresp, err := client.RequestLogs().GetRequestLogStats(ctx, req)\n\tif err != nil {\n\t\tlog.Fatalf(\"call: %v\", err)\n\t}\n\n\tfmt.Printf(\"%+v\\n\", resp)\n}\n"},{"name":"go.mod","content":"module github.com/tetrateio/agentrouter-go-examples/requestlogs/getrequestlogstats\n\ngo 1.26\n\nrequire github.com/tetrateio/agentrouter-go v0.1.1\n\n// Point this at the directory you extracted the downloaded Go SDK tarball into.\n// The directory name matches the tarball stem on the Download SDK page.\nreplace github.com/tetrateio/agentrouter-go =\u003e ./third_party/agentrouter-go-0.1.1\n"}]},"python":{"files":[{"name":"main.py","content":"\"\"\"Runnable example for the AgentRouter Python SDK.\n\nSet AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `python main.py`.\n\"\"\"\nimport os\n\nfrom tars.insights.v1 import request_logs_pb2\n\nfrom agentrouter_sdk import Client\n\nclient = Client(\n base_url=os.environ[\"AGENTROUTER_BASE_URL\"],\n api_key=os.environ[\"AGENTROUTER_API_KEY\"],\n)\n\n# Populate the request fields -- see the \"Request fields\" table above\n# for the available fields and which are required.\nreq = request_logs_pb2.GetRequestLogStatsRequest()\ntry:\n result = client.request_logs.get_request_log_stats(req)\n print(result)\nexcept Exception as err:\n print(\"Error:\", err)\n"},{"name":"requirements.txt","content":"# Point this at the directory you extracted the downloaded Python SDK tarball\n# into. The directory name matches the tarball stem on the Download SDK page.\n# To install instead from PyPI once published, replace the line below with:\n# agentrouter-sdk\u003e=0.1.0\nagentrouter-sdk @ file:./third_party/agentrouter-python-0.1.1\n"}]},"typescript":{"files":[{"name":"index.ts","content":"// Runnable example for the AgentRouter TypeScript SDK.\n// Set AGENTROUTER_BASE_URL and AGENTROUTER_API_KEY in the environment, then run `npm install \u0026\u0026 npx tsx index.ts`.\nimport { Client } from '@tetrate/agentrouter-sdk'\n\nconst client = new Client({\n baseUrl: process.env.AGENTROUTER_BASE_URL,\n apiKey: process.env.AGENTROUTER_API_KEY,\n})\n\n// Populate the request fields -- see the \"Request fields\" table above\n// for the available fields and which are required.\nconst req = {}\ntry {\n const result = await client.requestLogs.getRequestLogStats(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"requestlogs\",\n \"version\": \"0.1.0\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@tetrate/agentrouter-sdk\": \"file:./third_party/agentrouter-typescript-0.1.1\"\n },\n \"devDependencies\": {\n \"@types/node\": \"^20.0.0\",\n \"typescript\": \"^5.4.0\"\n }\n}\n"},{"name":"tsconfig.json","content":"{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true\n }\n}\n"}]},"cli":"tare api request-logs request-log-stats get","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/request-logs/stats\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Admin","httpVerb":"GET","httpPath":"/v1/request-logs/stats","slug":"get-request-log-stats"}