# RudderStack Organization Usage API


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]({{< ref "access-management/service-access-tokens.md#organization-sat" >}}) 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](https://swagger.io/docs/specification/authentication/bearer-authentication/) in the following format:

```
Authorization: Bearer <SERVICE_ACCESS_TOKEN>
```

{{< warning >}}
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`.
{{< /warning >}}

## Base URL

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

{{< tabs tabTotal="2" >}}
{{% tab tabName="Standard" %}}
```text
https://api.rudderstack.com/v2
```
{{% /tab %}}
{{% tab tabName="EU-Standard" %}}
```text
https://api.eu.rudderstack.com/v2
```
{{% /tab %}}
{{< /tabs >}}

## Get organization event usage metrics

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

{{% api-method method="get" host="https://api.rudderstack.com/v2" path="/organizations/usage/event-metrics" %}}

**Query parameters**

{{< query-params keyname="granularity" valuename="Time bucket size for event counts. It accepts one of the following values: `day`, `week`, or `month`." keytype="Required" datatype="String" >}}
{{< query-params keyname="start" valuename="Start date for the usage window in `YYYY-MM-DD` format, interpreted as midnight UTC. Must fall within the [maximum lookback window](#maximum-lookback-window) for the specified `granularity`." keytype="Required" datatype="String (date)" >}}
<hr/>

### 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`.

| `granularity` | Maximum lookback |
| :--- | :--- |
| `day` | 60 days |
| `week` | 9 weeks |
| `month` | 24 months |

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

{{< tabs tabTotal="2" >}}
{{% tab tabName="HTTP" %}}
```http
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>
```
{{% /tab %}}
{{% tab tabName="CURL" %}}
```bash
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>'
```
{{% /tab %}}
{{< /tabs >}}

**Example response**

```json
{
  "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**

{{< query-paramsList >}}
  {{< query-params keyname="data" valuename="Contains the event usage metric rows, grouped by workspace, source, and bucket." keytype="Required" datatype="Array" >}}
  {{< query-params keyname="workspaceId" valuename="Unique identifier of the workspace that owns the source." keytype="Required" datatype="String" >}}
  {{< query-params keyname="sourceId" valuename="Unique identifier of the source." keytype="Required" datatype="String" >}}
  {{< query-params keyname="sourceName" valuename="Display name of the source." keytype="Required" datatype="String" >}}
  {{< query-params keyname="sourceCategory" valuename="Source category. Known values are `eventStream`, `reverseEtl`, and `etl`." keytype="Required" datatype="String" >}}
  {{< query-params keyname="sourceDefinitionId" valuename="Unique identifier of the source definition." keytype="Required" datatype="String" >}}
  {{< query-params keyname="bucket" valuename="UTC date for the usage time bucket, returned as the left edge or start time of the bucket." keytype="Required" datatype="String (date)" >}}
  {{< query-params keyname="count" valuename="Event count for the source and bucket." keytype="Required" datatype="Number" >}}
  {{< query-params keyname="deleted" valuename="Indicates whether the source has since been deleted. Deleted sources are included when they contributed events in the requested window." keytype="Required" datatype="Boolean" >}}
  {{< query-params keyname="summary" valuename="Contains the aggregate event counts for the response." keytype="Required" datatype="Object" >}}
  {{< query-params keyname="totalEvents" valuename="Sum of all returned event counts." keytype="Required" datatype="Number" >}}
  {{< query-params keyname="eventStream" valuename="Sum of event counts for Event Stream sources." keytype="Required" datatype="Number" >}}
  {{< query-params keyname="reverseEtl" valuename="Sum of event counts for Reverse ETL sources." keytype="Required" datatype="Number" >}}
  {{< query-params keyname="etl" valuename="Sum of event counts for ETL sources." keytype="Required" datatype="Number" >}}
{{< /query-paramsList >}}

**Response codes**

| Code | Description |
| :----| :---|
| 200 | Returns organization-level event usage counts grouped by workspace, source, and time bucket. |
| 400 | Invalid query parameters. This includes missing or invalid `granularity`, missing or invalid `start`, and a `start` date older than the [maximum lookback window](#maximum-lookback-window) for the specified granularity. |
| 401 | Missing, invalid, or unsupported access token. Use an organization-level Service Access Token for this endpoint. |
| 500 | Upstream or internal error. |

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

```json
{
  "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`.