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, accessible programmatically via your PropelAuth API key.

Authentication

Authenticate with a Bearer token using your PropelAuth API key from Studio API Keys:

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

{
  "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

Python

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")

Custom date range grouped by file type

Python

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()

Filter by specific products

Use repeatable query parameters to filter results:

Python

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()

Grouping by async metadata

If you attach metadata to async jobs, 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:

{ "async": { "metadata": { "tenant_id": "acme" } } }

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:

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

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.

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.

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

Credit Usage

How credits are calculated per endpoint.

Account & Settings

Manage API keys, usage alerts, and billing in Studio.