--- title: "Get API Statistics" method: POST path: "/management/v1/endpoint-statistics" tags: ["project"] --- # Get API Statistics `POST /management/v1/endpoint-statistics` ## Request - Base URL: `https://localhost` - URL: `https://localhost/management/v1/endpoint-statistics` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieves detailed endpoint call statistics for your project, allowing you to monitor API usage patterns, track frequency of operations, and analyze response codes. ## Data Collection The statistics include: - Endpoint paths and HTTP methods - Response status codes - Call counts per endpoint - Warehouse context (when applicable) - Timestamps of activity ## Time Aggregation Statistics are aggregated hourly. Within each hour window: - An initial entry is created on the first API call - Subsequent calls update the existing hourly entry - Each hour boundary creates a new aggregation bucket - Hours with no API activity have no entries (gaps in data) ## Response Format The response includes timestamp buckets (in UTC) and corresponding endpoint metrics, allowing for time-series analysis of API usage patterns. Example: - 00:00:00-00:16:32: no activity - `timestamps: []` - 00:16:32: warehouse created: - `{timestamps: ["01:00:00"], called_endpoints: [[{"count": 1, "http_route": "POST /management/v1/warehouse", "status_code": 201, "warehouse_id": null, "warehouse_name": null, "created_at": "00:16:32", "updated_at": null}]]}` - 00:30:00: table created: - `timestamps: ["01:00:00"], called_endpoints: [[{"count": 1, "http_route": "POST /management/v1/warehouse", "status_code": 201, "warehouse_id": null, "warehouse_name": null, "created_at": "00:16:32", "updated_at": null}, {"count": 1, "http_route": "POST /catalog/v1/{prefix}/namespaces/{namespace}/tables", "status_code": 201, "warehouse_id": "ff17f1d0-90ad-4e7d-bf02-be718b78c2ee", "warehouse_name": "staging", "created_at": "00:30:00", "updated_at": null}]]` - 00:45:00: table created: - `timestamps: ["01:00:00"], called_endpoints: [[{"count": 1, "http_route": "POST /management/v1/warehouse", "status_code": 201, "warehouse_id": null, "warehouse_name": null, "created_at": "00:16:32", "updated_at": null}, {"count": 1, "http_route": "POST /catalog/v1/{prefix}/namespaces/{namespace}/tables", "status_code": 201, "warehouse_id": "ff17f1d0-90ad-4e7d-bf02-be718b78c2ee", "warehouse_name": "staging", "created_at": "00:30:00", "updated_at": "00:45:00"}]]` - 01:00:36: table deleted: - `timestamps: ["01:00:00","02:00:00"], called_endpoints: [[{"count": 1, "http_route": "POST /management/v1/warehouse", "status_code": 201, "warehouse_id": null, "warehouse_name": null, "created_at": "00:16:32", "updated_at": null},{"count": 1, "http_route": "POST /catalog/v1/{prefix}/namespaces/{namespace}/tables", "status_code": 201, "warehouse_id": "ff17f1d0-90ad-4e7d-bf02-be718b78c2ee", "warehouse_name": "staging", "created_at": "00:30:00", "updated_at": "00:45:00"}],[{"count": 1, "http_route": "DELETE /catalog/v1/{prefix}/namespaces/{namespace}/tables/{table}", "status_code": 200, "warehouse_id": "ff17f1d0-90ad-4e7d-bf02-be718b78c2ee", "warehouse_name": "staging", "created_at": "01:00:36", "updated_at": "null"}]]` ## Request body - GetEndpointStatisticsRequest - `range-specifier` union - object - `end` string, date-time, required: End timestamp of the time window Specify - `interval` string, required: Duration/span of the time window The returned statistics will be for the time window from `end` - `interval` to `end`. Specify a ISO8601 duration string, e.g. `PT1H` for 1 hour, `P1D` for 1 day. - `type` 'window', required - object - `token` string, required: Opaque Token from previous response for paginating through time windows Use the `next_page_token` or `previous_page_token` from a previous response - `type` 'page-token', required - `status-codes` integer[], nullable: Status code filter Optional filter to only return statistics for requests with specific status codes. - `warehouse` union, required - object: Filter for a specific warehouse - `id` string, uuid, required - `type` 'warehouse-id', required - object: Filter for items that are not associated with a warehouse - `type` 'unmapped', required - object: Return all items in the current project, regardless of warehouse association - `type` 'all', required ## Response `200` Endpoint statistics - EndpointStatisticsResponse - `called-endpoints` array[], required: Array of arrays of statistics detailing each called endpoint for each `timestamp`. See docs of `timestamps` for more details. - EndpointStatistic[] - `count` integer, required: Number of requests to this endpoint for the current time-slice. - `created-at` string, date-time, required: Timestamp at which the datapoint was created in the database. This is the exact time at which the current endpoint-status-warehouse combination was called for the first time in the current time-slice. - `http-route` string, required: The route of the endpoint. Format: `METHOD /path/to/endpoint` - `status-code` integer, required: The status code of the response. - `updated-at` string, date-time, nullable: Timestamp at which the datapoint was last updated. This is the exact time at which the current datapoint was last updated. - `warehouse-id` string, uuid, nullable: The ID of the warehouse that handled the request. Only present for requests that could be associated with a warehouse. Some management endpoints cannot be associated with a warehouse, e.g. warehouse creation or user management will not have a `warehouse-id`. - `warehouse-name` string, nullable: The name of the warehouse that handled the request. Only present for requests that could be associated with a warehouse. Some management endpoints cannot be associated with a warehouse, e.g. warehouse creation or user management will not have a `warehouse-id` - `next-page-token` string, required: Token to get the next page of results. Inverse of `previous-page-token`, see its documentation above. - `previous-page-token` string, required: Token to get the previous page of results. Endpoint statistics are not paginated through page-limits, we paginate them by stepping through time. By default, the list-statistics endpoint will return all statistics for `now()` - 1 day to `now()`. In the request, you can specify a `range_specifier` to set the end date and step interval. The `previous-page-token` will then move to the neighboring window. E.g. in the default case of `now()` and 1 day, it'd be `now()` - 2 days to `now()` - 1 day. - `timestamps` string[], required: Array of timestamps indicating the time at which each entry in the `called_endpoints` array is valid. We lazily create a new statistics entry every hour, in between hours, the existing entry is being updated. If any endpoint is called in the following hour, there'll be an entry in `timestamps` for the following hour. If not, then there'll be no entry. ## Other responses - `4XX` --- [API](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api.md) - [All operations](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lakekeeper/apis/lakekeeper-management-api/revisions/c5cb9a12a98c?raw)