Usage Export API

The Usage Export API returns the same usage data available on the Studio usage dashboard, accessible programmatically via your PropelAuth API key. It covers the last 90 days of usage. The unit depends on your pricing model. Accounts on per-product pricing receive pages. Accounts on credit-based pricing receive credits. See Response and the Pricing Migration Guide to find out which model applies to you.

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. Must be within the last 90 days.
`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`. Accounts on per-product pricing can use `product` or `api_key` only.
`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. Credit-based pricing only. 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.

Data retention

The API serves the last 90 days of usage, the same range as the Studio “Last 90 days” view: today plus the 89 days before it. An earlier startDate returns a 400 error.

Response

The metric field tells you which unit the data entries carry: pages or credits. Each entry in data represents one day and one group value.

Per-product pricing

Reducto bills these accounts per page. Each entry carries pages. See Usage and Pricing.

{
  "orgId": "org_abc123",
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "groupBy": "product",
  "metric": "pages",
  "data": [
    {
      "date": "2026-09-01",
      "group": "parse",
      "pages": 1200
    },
    {
      "date": "2026-09-01",
      "group": "extract",
      "pages": 340
    }
  ]
}

These accounts can group by product or api_key. Other groupBy values return a 400 error.

Credit-based pricing

Reducto bills these accounts in credits. Each entry carries credits, the total credits consumed.

{
  "orgId": "org_abc123",
  "startDate": "2026-05-19",
  "endDate": "2026-06-18",
  "groupBy": "product",
  "metric": "credits",
  "data": [
    {
      "date": "2026-05-19",
      "group": "parse",
      "credits": 150.0
    },
    {
      "date": "2026-05-19",
      "group": "extract",
      "credits": 80.0
    }
  ]
}

These accounts can use every groupBy value, including metadata.

API key grouping

With groupBy=api_key, group is the key prefix and groupName is the key’s name in Studio. groupName is null for keys that no longer exist.

{
  "date": "2026-09-01",
  "group": "rk_live_ab12",
  "groupName": "production",
  "pages": 1200
}

Examples

Default: last 30 days grouped by product

import requests

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

unit = data["metric"]
for row in data["data"]:
    print(f"{row['date']} | {row['group']}: {row[unit]} {unit}")

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

const unit = data.metric;
for (const row of data.data) {
  console.log(`${row.date} | ${row.group}: ${row[unit]} ${unit}`);
}

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export"

Custom date range grouped by file type

Available on credit-based pricing. Accounts on per-product pricing group by product or api_key.

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

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

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"

Filter by specific products

Use repeatable query parameters to filter results. This example groups by feature, which is available on credit-based pricing:

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

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

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://studio.reducto.ai/api/v1/usage/export?groupBy=feature&product=parse&product=extract"

Grouping by async metadata

Available on credit-based pricing. 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, or a `groupBy` other than `product` or `api_key` on per-product pricing
`400`	`metadataKey` or `metadataValue` on per-product pricing
`400`	More than 100 values for one filter parameter
`400`	`startDate` or `endDate` not in `yyyy-mm-dd` format, `endDate` before `startDate`, or `startDate` before the earliest retained date (today minus 89 days)
`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

Pricing and Usage

How Reducto prices pages and credits per endpoint.

Account & Settings

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

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources

Usage Export API

Authentication

Endpoint

Query Parameters

Data retention

Response

Per-product pricing

Credit-based pricing

API key grouping

Examples

Default: last 30 days grouped by product

Custom date range grouped by file type

Filter by specific products

Grouping by async metadata

Multi-Organization Access

Error Responses

Pricing and Usage

Account & Settings

​Authentication

​Endpoint

​Query Parameters

​Data retention

​Response

​Per-product pricing

​Credit-based pricing

​API key grouping

​Examples

​Default: last 30 days grouped by product

​Custom date range grouped by file type

​Filter by specific products

​Grouping by async metadata

​Multi-Organization Access

​Error Responses

​Related

Pricing and Usage

Account & Settings

Authentication

Endpoint

Query Parameters

Data retention

Response

Per-product pricing

Credit-based pricing

API key grouping

Examples

Default: last 30 days grouped by product

Custom date range grouped by file type

Filter by specific products

Grouping by async metadata

Multi-Organization Access

Error Responses

Related