Query gateway requests and runtime logs

You can query your ’s request log and runtime logs with SQL, to build your own dashboards, alerts, or exports. Each table has its own endpoint and permission.

Table	Endpoint	Root key permission
`gateway_requests_v1`	`POST /v2/analytics.getGatewayRequests`	`project.*.read_gateway_requests`
`runtime_logs_v1`	`POST /v2/analytics.getRuntimeLogs`	`project.*.read_runtime_logs`

You need a root key with the wildcard (project.*) permission for the table. A permission for a single project doesn’t work here. Create the key under Settings > Root Keys and send it as Authorization: Bearer <root key>. See Root keys.

Query rules

Only SELECT runs. CTEs, subqueries, UNION, and EXCEPT are fine.
You only ever see your own workspace’s data. To narrow further, filter on project_id, app_id, or environment_id.
The time range can’t reach back further than your plan’s log query range (3 days on Starter, 7 on Pro, 14 on Business), or the query fails with query_range_exceeds_retention. See Compute limits.
A result larger than 4 MiB fails with query_memory_limit_exceeded.

The response is {"meta":{"requestId":...},"data":[...]} with one object per row.

Examples

curl -X POST https://api.unkey.com/v2/analytics.getGatewayRequests \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT path, count() AS total FROM gateway_requests_v1 WHERE response_status >= 500 AND time >= toUnixTimestamp64Milli(now64(3) - INTERVAL 24 HOUR) GROUP BY path ORDER BY total DESC LIMIT 10"}'

unkey api analytics get-gateway-requests \
  --query="SELECT path, count() AS total FROM gateway_requests_v1 WHERE response_status >= 500 AND time >= toUnixTimestamp64Milli(now64(3) - INTERVAL 24 HOUR) GROUP BY path ORDER BY total DESC LIMIT 10"

curl -X POST https://api.unkey.com/v2/analytics.getRuntimeLogs \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT time, severity, message FROM runtime_logs_v1 WHERE lower(message) LIKE '"'"'%timeout%'"'"' ORDER BY time DESC LIMIT 100"}'

unkey api analytics get-runtime-logs \
  --query="SELECT time, severity, message FROM runtime_logs_v1 WHERE lower(message) LIKE '%timeout%' ORDER BY time DESC LIMIT 100"

time is a Unix timestamp in milliseconds in both tables, so the examples compare it with toUnixTimestamp64Milli(...).

gateway_requests_v1

One row per request that reached your app. Requests a policy rejected aren’t here. See Request logs.

String

The request ID, also sent as X-Unkey-Request-Id.

Int64

Unix timestamp in milliseconds when the gateway received the request.

String

Your workspace, the one the root key belongs to.

String

The project.

String

The app.

String

The environment.

String

The deployment that served the request.

String

The instance that served the request.

String

The region of the gateway that served the request.

String

Upper-case HTTP method.

String

The requested hostname.

String

The request path without the query string.

String

The raw query string. Empty unless a logging policy captured query data.

Map(String, Array(String))

Parsed query parameters. Empty unless a logging policy captured query data.

Array(String)

Key: Value strings. Empty unless a logging policy captured request headers. API keys are redacted.

String

Up to 1 MiB. Empty unless a logging policy captured the request body.

Int32

The status the client received.

Array(String)

Key: Value strings. Empty unless a logging policy captured response headers.

String

Up to 1 MiB. Empty unless a logging policy captured the response body.

String

Empty unless a logging policy captured request headers.

String

The client IP. Empty unless a logging policy captured request headers.

Int64

Milliseconds from receipt to the end of the response.

Int64

Milliseconds spent by your instance.

Int64

total_latency minus instance_latency.

runtime_logs_v1

One row per log line from your instances. Structured attributes are in attributes_text, as a JSON string.

String

Stable identifier of the log line.

Int64

Unix timestamp in milliseconds when the line was written.

Int64

Unix timestamp in milliseconds when the line was stored. Filter on it as well as on time to make queries over a wide range faster.

String

Lower-case severity parsed from the line, info when none was found.

String

The message, with color codes removed.

String

Your workspace.

String

The project.

String

The environment.

String

The app.

String

The deployment whose instance wrote the line.

String

The region the instance ran in.

String

The parsed attributes as a JSON string. Search it with lower(attributes_text) LIKE '%...%', which the table indexes.

Get started

Concepts

Build

Configure

Networking

Gateway

Observe

Query gateway requests and runtime logs

Query rules

Examples

gateway_requests_v1

runtime_logs_v1

​Query rules

​Examples

​gateway_requests_v1

​runtime_logs_v1

Query rules

Examples

gateway_requests_v1

runtime_logs_v1