> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Export API

> Programmatically export usage and credit data from your Reducto account

The Usage Export API returns the same usage data available on the [Studio usage dashboard](/studio-account#usage), accessible programmatically via your PropelAuth API key.

## Authentication

Authenticate with a Bearer token using your PropelAuth API key from [Studio API Keys](https://studio.reducto.ai/):

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export"
```

This is your personal API key from the Studio API Keys page, not the `REDUCTO_API_KEY` used for document processing.

## Endpoint

```
GET https://studio.reducto.ai/api/v1/usage/export
```

## Query Parameters

| Parameter       | Type     | Default       | Description                                                                                                                                                                                                          |
| --------------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startDate`     | `string` | 30 days ago   | Start date in `yyyy-mm-dd` format                                                                                                                                                                                    |
| `endDate`       | `string` | Today         | End date in `yyyy-mm-dd` format                                                                                                                                                                                      |
| `groupBy`       | `string` | `product`     | Dimension to group results by. One of: `product`, `feature`, `api_key`, `file_type`, `metadata`                                                                                                                      |
| `metadataKey`   | `string` | (none)        | Async metadata key to group or filter by. Required when `groupBy=metadata` or when using `metadataValue`. Enable the key for your organization first. See [Grouping by async metadata](#grouping-by-async-metadata). |
| `metadataValue` | `string` | (none)        | Filter by an async metadata value. Repeatable for multiple values; requires `metadataKey`.                                                                                                                           |
| `orgId`         | `string` | API key's org | Target organization ID. Required if your account belongs to multiple organizations.                                                                                                                                  |
| `product`       | `string` | (none)        | Filter by product. Repeatable for multiple values.                                                                                                                                                                   |
| `feature`       | `string` | (none)        | Filter by feature. Repeatable for multiple values.                                                                                                                                                                   |
| `apiKey`        | `string` | (none)        | Filter by API key. Repeatable for multiple values.                                                                                                                                                                   |
| `fileType`      | `string` | (none)        | Filter by file type. Repeatable for multiple values.                                                                                                                                                                 |

## Response

```json theme={null}
{
  "orgId": "org_abc123",
  "startDate": "2026-05-19",
  "endDate": "2026-06-18",
  "groupBy": "product",
  "data": [
    {
      "date": "2026-05-19",
      "group": "parse",
      "credits": 150.0,
      "requestCount": 75
    },
    {
      "date": "2026-05-19",
      "group": "extract",
      "credits": 80.0,
      "requestCount": 20
    }
  ]
}

```

Each entry in `data` represents one day and one group value. `credits` is the total credits consumed and `requestCount` is the number of API requests made.

## Examples

### Default: last 30 days grouped by product

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://studio.reducto.ai/api/v1/usage/export",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  data = response.json()

  for row in data["data"]:
      print(f"{row['date']} | {row['group']}: {row['credits']} credits, {row['requestCount']} requests")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://studio.reducto.ai/api/v1/usage/export",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await response.json();

  for (const row of data.data) {
    console.log(`${row.date} | ${row.group}: ${row.credits} credits, ${row.requestCount} requests`);
  }
  ```

  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://studio.reducto.ai/api/v1/usage/export"
  ```
</CodeGroup>

### Custom date range grouped by file type

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://studio.reducto.ai/api/v1/usage/export",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={
          "startDate": "2026-06-01",
          "endDate": "2026-06-15",
          "groupBy": "file_type",
      },
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    startDate: "2026-06-01",
    endDate: "2026-06-15",
    groupBy: "file_type",
  });

  const response = await fetch(
    `https://studio.reducto.ai/api/v1/usage/export?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://studio.reducto.ai/api/v1/usage/export?startDate=2026-06-01&endDate=2026-06-15&groupBy=file_type"
  ```
</CodeGroup>

### Filter by specific products

Use repeatable query parameters to filter results:

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://studio.reducto.ai/api/v1/usage/export",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params=[
          ("groupBy", "feature"),
          ("product", "parse"),
          ("product", "extract"),
      ],
  )
  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams();
  params.append("groupBy", "feature");
  params.append("product", "parse");
  params.append("product", "extract");

  const response = await fetch(
    `https://studio.reducto.ai/api/v1/usage/export?${params}`,
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://studio.reducto.ai/api/v1/usage/export?groupBy=feature&product=parse&product=extract"
  ```
</CodeGroup>

## Grouping by async metadata

If you attach [metadata to async jobs](/workflows/async-overview), you can break usage down by it. Use this to attribute credits to your own end customers without issuing a separate API key per tenant:

```json theme={null}
{ "async": { "metadata": { "tenant_id": "acme" } } }
```

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export?groupBy=metadata&metadataKey=tenant_id"
```

Each returned `group` is one value of that key. You can also filter to specific values while grouping by something else. This returns per-product usage for a single tenant:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export?groupBy=product&metadataKey=tenant_id&metadataValue=acme"
```

<Note>
  Contact support with the key names you want enabled before using them as a usage dimension. Reducto gates this deliberately: async metadata is free-form and often carries webhook credentials or per-request identifiers, and neither belongs in usage reporting.
</Note>

Things to know:

* **Only async jobs carry metadata.** Synchronous requests have no `async.metadata`, so their usage appears under `unknown`.
* **Reducto groups jobs missing the key under `unknown`.** That includes jobs you submitted before you started sending the key, so historical totals show a large `unknown` bucket.
* **Keep keys low-cardinality.** A key that labels tenants, customers, or departments works. Reducto rejects a key carrying a per-request identifier, such as a document id or a signature, because it produces one group per request.
* **Reducto compares values as text** and truncates them to 256 characters. You cannot group by a nested object or an array.
* **`credits` still reconciles.** For any single `metadataKey`, the per-group credits plus the `unknown` bucket equal your total credits for that period.
* **`metadataKey` on its own narrows the results.** Passing it without `groupBy=metadata` restricts the response to jobs that carried that key, so totals cover a subset of your usage. `groupBy=file_type&metadataKey=tenant_id` returns the file-type breakdown of jobs that carried `tenant_id`, and adds no `unknown` bucket.

## Multi-Organization Access

If your account belongs to multiple organizations, pass the `orgId` parameter to specify which organization's usage to retrieve. Without it, the API defaults to the organization associated with your API key.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export?orgId=org_abc123"
```

You can only query organizations you are a member of. Requesting an org you don't belong to returns a `403` error.

## Error Responses

| Status | Meaning                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing or invalid API key                                                                                       |
| `400`  | Invalid `groupBy` value                                                                                          |
| `400`  | `groupBy=metadata` or `metadataValue` without `metadataKey`, or a `metadataKey` not enabled for the organization |
| `403`  | Not a member of the requested organization                                                                       |
| `500`  | Server error                                                                                                     |

## Related

<CardGroup cols={2}>
  <Card title="Credit Usage" icon="coins" href="/reference/credit-usage">
    How credits are calculated per endpoint.
  </Card>

  <Card title="Account & Settings" icon="gear" href="/studio-account">
    Manage API keys, usage alerts, and billing in Studio.
  </Card>
</CardGroup>