Customer request logs
Package: agentrouter.insights.v1 Service: CustomerRequestLogsService
Endpoints
List request logs scoped to the calling user
What it does: Returns the caller's own request logs, filtered by the supplied tenancy scope. Forced filter: user_id = caller.UserID.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Tenancy scope. Defaults to the caller's session customer_id / project_id when empty. |
project_id | no | Project within the customer to scope the query to. |
api_key_id | no | Optional filters. Mirror QueryRequestLogsRequest minus user_id (forced to caller). Restrict to logs produced by this API key (UUID). |
model_name | no | Restrict to a single model name (e.g. "claude-3-opus", "gpt-4"). |
status | no | Restrict by logical status (e.g. "success", "error", "timeout"). |
status_code | no | Restrict by HTTP status code returned to the client. |
start_time | no | Start of the time range (inclusive). |
end_time | no | End of the time range (exclusive). |
min_duration_ms | no | Only include requests at least this many milliseconds long. |
max_duration_ms | no | Only include requests at most this many milliseconds long. |
page_size | no | Pagination. Maximum logs per page (server applies a default and cap). |
page_token | no | Opaque token from a prior response's next_page_token to fetch the next page. |
order_by | no | Ordering. Valid order_by: timestamp, duration_ms, input_tokens, output_tokens. Valid order_direction: asc, desc. |
order_direction | no | Sort direction for order_by: "asc" or "desc". |
Response fields:
| Field | Required | Description |
|---|---|---|
logs | no | Request logs for the caller on this page, newest first by default. |
next_page_token | no | Token to pass back as page_token for the next page; empty when exhausted. |
total_count | no | Total number of matching logs across all pages (may be approximate). |
{"signatures":{"go":"func (x *CustomerRequestLogsClient) ListCustomerRequestLogs(ctx context.Context, req *insightsv1.ListCustomerRequestLogsRequest) (*insightsv1.ListCustomerRequestLogsResponse, error)","python":"list_customer_request_logs(req: request_logs_pb2.ListCustomerRequestLogsRequest) -\u003e ListCustomerRequestLogsResponse","typescript":"listCustomerRequestLogs(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.ListCustomerRequestLogsRequestSchema \u003e): Promise\u003cListCustomerRequestLogsResponse\u003e","cli":"tare api insights logs list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs\" \\\n -H \"Authorization: Bearer ${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.ListCustomerRequestLogsRequest{}\n\n\tresp, err := client.CustomerRequestLogs().ListCustomerRequestLogs(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/customerrequestlogs/listcustomerrequestlogs\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.ListCustomerRequestLogsRequest()\ntry:\n result = client.customer_request_logs.list_customer_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.customerRequestLogs.listCustomerRequestLogs(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"customerrequestlogs\",\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 insights logs list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs\" \\\n -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/request-logs","slug":"list-request-logs-scoped-to-the-calling-user"}Get a single request log
What it does: Returns a single request log row owned by the calling user. Cross-user NotFound: the user cannot read another user's log even within the same customer/project.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Defaults to the caller's session customer_id / project_id when empty. |
project_id | no | undocumented |
request_id | yes | Identifier of the request log to fetch; must be owned by the caller. |
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 *CustomerRequestLogsClient) GetCustomerRequestLog(ctx context.Context, req *insightsv1.GetCustomerRequestLogRequest) (*insightsv1.RequestLog, error)","python":"get_customer_request_log(req: request_logs_pb2.GetCustomerRequestLogRequest) -\u003e RequestLog","typescript":"getCustomerRequestLog(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.GetCustomerRequestLogRequestSchema \u003e): Promise\u003cRequestLog\u003e","cli":"tare api insights logs get --request-id $REQUEST_ID","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs/01H...\" \\\n -H \"Authorization: Bearer ${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.GetCustomerRequestLogRequest{}\n\n\tresp, err := client.CustomerRequestLogs().GetCustomerRequestLog(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/customerrequestlogs/getcustomerrequestlog\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.GetCustomerRequestLogRequest()\ntry:\n result = client.customer_request_logs.get_customer_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.customerRequestLogs.getCustomerRequestLog(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"customerrequestlogs\",\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 insights logs get --request-id $REQUEST_ID","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs/01H...\" \\\n -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/request-logs/{request_id}","slug":"get-a-single-request-log"}Aggregate stats over the caller's request logs
What it does: Returns aggregated statistics over the calling user's request logs within the supplied tenancy scope.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | Defaults to the caller's session customer_id / project_id when empty. |
project_id | no | undocumented |
model_name | no | Optional filter restricting stats to a single model name. |
start_time | no | Start of the aggregation time range (inclusive). |
end_time | no | End of the aggregation time range (exclusive). |
group_by | no | Dimension to group by: "model", "user", "api_key", "status", "hour", "day". |
metric | no | Metric to compute: "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 *CustomerRequestLogsClient) GetCustomerRequestLogStats(ctx context.Context, req *insightsv1.GetCustomerRequestLogStatsRequest) (*insightsv1.RequestLogStatsResponse, error)","python":"get_customer_request_log_stats(req: request_logs_pb2.GetCustomerRequestLogStatsRequest) -\u003e RequestLogStatsResponse","typescript":"getCustomerRequestLogStats(req: MessageInitShape\u003c typeof tars_insights_v1_request_logs_pb.GetCustomerRequestLogStatsRequestSchema \u003e): Promise\u003cRequestLogStatsResponse\u003e","cli":"tare api insights logs stats","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs/stats\" \\\n -H \"Authorization: Bearer ${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.GetCustomerRequestLogStatsRequest{}\n\n\tresp, err := client.CustomerRequestLogs().GetCustomerRequestLogStats(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/customerrequestlogs/getcustomerrequestlogstats\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.GetCustomerRequestLogStatsRequest()\ntry:\n result = client.customer_request_logs.get_customer_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.customerRequestLogs.getCustomerRequestLogStats(req)\n console.log(result)\n} catch (err) {\n console.error('Error:', err)\n}\n"},{"name":"package.json","content":"{\n \"name\": \"customerrequestlogs\",\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 insights logs stats","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../request-logs/stats\" \\\n -H \"Authorization: Bearer ${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/request-logs/stats","slug":"aggregate-stats-over-the-callers-request-logs"}