Query gateway request data

A query can use only the public alias gateway_requests_v1. CTEs, subqueries, UNION, and EXCEPT are permitted. The root key must have the project.*.read_gateway_requests permission. Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on project_id, app_id, or environment_id. The workspace retention period and the workspace query limits apply. For the columns and more query examples, see the gateway request analytics documentation.

POST /v2/analytics.getGatewayRequests

Typescript (SDK)

TypeScript

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.analytics.getGatewayRequests({
    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",
  });

  console.log(result);
}

run();

200

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "path": "/v1/orders",
      "total": 1234
    }
  ]
}

Authorizations

Authorization · string · header · required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

• Keep root keys secure and never expose them in client-side code
• Use different root keys for different environments
• Rotate keys periodically, especially after team member departures
• Create keys with minimal necessary permissions following least privilege principle
• Monitor key usage with audit logs.

Body

application/json

query · string · required

The SQL query to run on your gateway request data. A query can use only the public alias gateway_requests_v1. The physical default.* table names are not permitted. Only SELECT queries are permitted. CTEs, subqueries, UNION, and EXCEPT are also permitted. Unkey limits each query to the workspace of the root key. To get the data for one project, app, or environment, add a filter on project_id, app_id, or environment_id. The workspace retention period and the workspace query limits apply.

Example:

"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"

Response

200

application/json

Query executed successfully

meta · object · required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

Show child attributes

data · object[] · required

The gateway request rows that the query returned. The SELECT clause of the query controls the fields in each row.

Example:

[{ "path": "/v1/orders", "total": 1234 }]