RudderStack Organization Usage API Beta

The Organization Usage API lets you get organization-level event usage counts grouped by workspace, source, and time bucket.

You can use this API to reconcile your organization’s event usage and billing numbers across Event Stream, Reverse ETL, and ETL sources.

Prerequisites

• Generate an organization-level Service Access Token in the RudderStack dashboard to authenticate the API.
• Use the API base URL for your RudderStack region.

Authentication

The Organization Usage API uses Bearer authentication in the following format:

Authorization: Bearer <SERVICE_ACCESS_TOKEN>

This endpoint requires an organization-level Service Access Token. Workspace-level Service Access Tokens and Personal Access Tokens are not supported for this endpoint and return 401 Unauthorized.

Base URL

Use the base URL for your API requests depending on your region:

https://api.rudderstack.com/v2

https://api.eu.rudderstack.com/v2

Get organization event usage metrics

You can get organization-level event usage metrics using the following endpoint:

Query parameters

Maximum lookback window

If start is older than the window for the specified granularity (relative to the current time in UTC), the API returns 400 Bad Request.

Buckets are left-aligned: the bucket value is the bucket’s start time, not its end time.

Rows with deleted: true represent sources that have since been deleted but still contributed events in the requested window. These rows are included in the results, not filtered out.

Example request

GET /v2/organizations/usage/event-metrics?granularity=day&start=2024-07-01 HTTP/1.1
Host: api.rudderstack.com
Accept: application/json
Authorization: Bearer <SERVICE_ACCESS_TOKEN>

curl --location 'https://api.rudderstack.com/v2/organizations/usage/event-metrics?granularity=day&start=2024-07-01' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <SERVICE_ACCESS_TOKEN>'

Example response

{
  "data": [
    {
      "workspaceId": "abc123",
      "sourceId": "src_xyz",
      "sourceName": "JavaScript",
      "sourceCategory": "eventStream",
      "sourceDefinitionId": "def_001",
      "bucket": "2024-07-01",
      "count": 15230,
      "deleted": false
    },
    {
      "workspaceId": "abc123",
      "sourceId": "src_wh",
      "sourceName": "Warehouse Action",
      "sourceCategory": "reverseEtl",
      "sourceDefinitionId": "def_002",
      "bucket": "2024-07-01",
      "count": 4200,
      "deleted": false
    }
  ],
  "summary": {
    "totalEvents": 19430,
    "eventStream": 15230,
    "reverseEtl": 4200,
    "etl": 0
  }
}

Response object parameters

Response codes

Example 400 response when start exceeds the lookback window for granularity=day:

{
  "code": "bad-request",
  "error": "start date too far in the past for '1 day' granularity",
  "details": {}
}

The error text uses '1 day', '1 week', or '1 month' even though the granularity query parameter is day, week, or month.