> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get usage for a date range > Return an organization's usage for `[start_date, end_date)`, in one bucket per calendar month, clipped to the range and ending at the current month. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. An event counts in the month that contains its `start_time`, which the client sets when it logs the event, so usage for a past month can still grow. `metrics_computed_count` is the number of `metrics.*` keys on those events. Results are always split by `event_type`; pass `group_by` to also split them by workspace or by project. Every row is returned in one response; there is no pagination. Quarter- and year-to-date totals are for the caller to sum across ranges. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/control_plane_openapi.yaml get /v1/orgs/{org_id}/usage openapi: 3.1.0 info: title: HoneyHive Control Plane API description: > Manage HoneyHive control-plane resources: workspaces, projects and alerts, and read org usage. Authentication requires a fine-grained control-plane API key (values start with `hh_fgcp_`), sent as `Authorization: Bearer `. Project API keys used with the Data Plane API will not work here. Create a key in the HoneyHive app under an organization's or workspace's **Settings → API Keys**, or see [Authorization](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript#authorization) for details. license: name: MIT url: https://opensource.org/licenses/MIT version: 1.17.0 servers: - url: https://api.cp.us.honeyhive.ai security: [] tags: - name: Alerts description: > Define and manage alerts. Alerts evaluate event metrics on a schedule and trigger notifications when configured thresholds are crossed. - name: Projects description: > Create and manage projects within a workspace. A project is the container for the events, datasets, evaluations, and alerts logged against it. - name: Usage description: > Read an organization's usage: events and computed metrics per calendar month, and current user, workspace and project counts. - name: Virtual Dataplanes description: > Create and manage virtual data planes. A virtual data plane is a logical tenant boundary inside an organization, hosted on a physical cluster; several virtual data planes commonly share one cluster. Workspaces live inside a virtual data plane. - name: Workspaces description: > Read and manage workspaces. A workspace groups the projects belonging to one team or environment, and owns the API keys and AI provider secrets its projects share. paths: /v1/orgs/{org_id}/usage: get: tags: - Usage summary: Get usage for a date range description: > Return an organization's usage for `[start_date, end_date)`, in one bucket per calendar month, clipped to the range and ending at the current month. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. An event counts in the month that contains its `start_time`, which the client sets when it logs the event, so usage for a past month can still grow. `metrics_computed_count` is the number of `metrics.*` keys on those events. Results are always split by `event_type`; pass `group_by` to also split them by workspace or by project. Every row is returned in one response; there is no pagination. Quarter- and year-to-date totals are for the caller to sum across ranges. operationId: getUsage parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization - in: query name: start_date required: true schema: type: string format: date description: Inclusive start, `YYYY-MM-DD` (UTC), no later than today - in: query name: end_date required: true schema: type: string format: date description: Exclusive end, `YYYY-MM-DD` (UTC), 1 to 92 days after `start_date` - in: query name: group_by required: false schema: type: string enum: - workspace_id - project_id description: > Split results by workspace, or by project (each project row also carries its workspace) responses: '200': description: Usage computed successfully content: application/json: schema: $ref: '#/components/schemas/GetUsageResponse' '400': description: >- Missing or malformed dates, a range outside 1 to 92 days, a `start_date` after today, an unknown `group_by`, or an unknown query parameter '404': description: >- Organization not found, or the caller may not read its usage. The response does not say which. '422': description: >- The usage query exceeded its time budget (`errorCode` `query_timeout`) or its memory budget (`errorCode` `query_too_large`). Request a shorter range, or omit `group_by`. security: - ControlPlaneApiKey: [] components: schemas: GetUsageResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/Usage' required: - success - data additionalProperties: false description: Org usage for a date range, in monthly buckets Usage: type: object properties: generated_at: type: string description: ISO-8601 timestamp the response was computed at start_date: type: string description: Calendar date, YYYY-MM-DD (UTC) end_date: type: string description: Calendar date, YYYY-MM-DD (UTC) buckets: type: array items: $ref: '#/components/schemas/UsageBucket' description: >- One bucket per calendar month in the range, through the current month. Every row is returned; there is no pagination required: - generated_at - start_date - end_date - buckets additionalProperties: false UsageBucket: type: object properties: start_date: type: string description: Inclusive bucket start end_date: type: string description: Exclusive bucket end results: type: array items: $ref: '#/components/schemas/UsageResult' required: - start_date - end_date - results additionalProperties: false UsageResult: type: object properties: workspace_id: type: string workspace_slug: type: string description: The workspace scope name workspace_label: type: string description: The workspace scope label, or the slug if the label is empty project_id: type: string project_slug: type: string description: The project scope name project_label: type: string description: The project scope label, or the slug if the label is empty event_type: type: string event_count: type: integer minimum: 0 metrics_computed_count: type: integer minimum: 0 description: Number of metrics.* keys on the events required: - event_type - event_count - metrics_computed_count additionalProperties: false securitySchemes: ControlPlaneApiKey: type: http scheme: bearer description: >- A fine-grained control-plane API key (values begin with `hh_fgcp_`). Project API keys used with the Data Plane API will not work here. Create one in the HoneyHive app under an organization's or workspace's **Settings → API Keys**. ```` ## Related topics - [Get current usage counts](https://docs.honeyhive.ai/v2/control-plane-api-reference-autogen/usage/get-current-usage-counts.md) - [GetChartResponse](https://docs.honeyhive.ai/v2/sdk-reference/typescript/ref/charts/GetChartResponse.md) - [GetChartsResponse](https://docs.honeyhive.ai/v2/sdk-reference/typescript/ref/charts/GetChartsResponse.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.