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

# Usage and limits

> What your organization used, the monthly statement, and your contract limits

These calls need the `usage:read` scope.

## Usage

`GET /api/org/v1/usage` returns what your organization used, by day or by month, in total
and for each workspace (`externalId`). Days are UTC, counted on the day a job was created.

```bash theme={null}
curl "https://api.clustr-ai.com/api/org/v1/usage?from=2026-10-01&to=2026-10-13&by=day" \
  -H "Authorization: Bearer $CLUSTR_ORG_KEY"
```

| Field | Meaning |
| - | - |
| `connectorsProcessed` | Connectors in the day's import jobs that completed. This is the unit of your monthly volume. |
| `profilesFresh`, `profilesCached` | Profiles delivered, split into new ones and ones Clustr already knew. |
| `exportRows` | Rows written to your data stores by exports. |

Parameters: `from` and `to` (dates, `to` inclusive, default the last 30 days), `by=day|month`,
and `tenant` (one workspace, by id or `external_id`).

## Monthly statement

`GET /api/org/v1/usage/statement?month=2026-10` is the monthly statement: one line for each
workspace `externalId`, a total, and your limits. Add `format=csv` for a CSV file.

## Contract limits

`GET /api/org/v1/limits` returns your limits:

* `monthlyConnectorLimit`: connectors you may process per UTC month. `null` means no limit.
* `maxJobSize`: the largest job. `null` means 1,000.

A job that would go over either is refused with `422` and code `ORG_LIMIT_EXCEEDED`. The
message says which limit, how much is used and how much is left. Clustr staff change the
limits. Ask your contact.

## In MCP

Organization admins have `org_get_usage`, `org_get_usage_statement` and `org_get_limits`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.