# Billing Folders Usage Report

**Endpoint**

<mark style="color:green;">`POST`</mark> `https://api.roboflow.com/{workspace_url}/billing-usage-report`

**Authentication**

API key with `workspaceStats.read` scope, passed as a query parameter (`?api_key=YOUR_API_KEY`).

**Rate Limit**

10 requests per minute per API key.

#### Request Parameters <a href="#request-parameters" id="request-parameters"></a>

All parameters are passed in the request body as JSON. All are optional.

| Parameter          | Type                | Default      | Description                                                                                                                                                           |
| ------------------ | ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startAt`          | string (ISO 8601)   | 7 days ago   | Start of the reporting period (inclusive)                                                                                                                             |
| `endAt`            | string (ISO 8601)   | Now          | End of the reporting period (exclusive)                                                                                                                               |
| `api_key_prefixes` | string or string\[] | All keys     | Filter to specific API key prefix(es). Each prefix is the first 5 characters of the full API key (e.g., `rf_ab` for key `rf_abCdEfGhIjK...`). Must be an exact match. |
| `features`         | string or string\[] | All features | Filter to specific billing feature(s)                                                                                                                                 |

#### Examples <a href="#examples" id="examples"></a>

{% tabs %}
{% tab title="Basic" %}
Default is last 7 days, all features, all api keys.

```shellscript
curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=YOUR_API_KEY"
```

{% endtab %}

{% tab title="Custom Date Range" %}

```shellscript
curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startAt": "2025-01-01T00:00:00.000Z",
    "endAt": "2025-02-01T00:00:00.000Z"
  }'
```

{% endtab %}

{% tab title="Filter By Feature" %}

```shellscript
curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "features": ["train", "serverless-inference-run"]
  }'
```

{% endtab %}

{% tab title="All Parameters" %}

```shellscript
curl -X POST "https://api.roboflow.com/my-workspace/billing-usage-report?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startAt": "2025-01-01T00:00:00.000Z",
    "endAt": "2025-02-01T00:00:00.000Z",
    "api_key_prefixes": ["rf_ab", "rf_de"],
    "features": ["train", "serverless-inference-run"]
  }'
```

{% endtab %}
{% endtabs %}

#### Response Schema <a href="#response-schema" id="response-schema"></a>

The API returns a JSON array of usage records:

```json
[
    {
        "api_key_prefix": "rf_ab",
        "feature": "train",
        "total_credits_used": 150.5,
        "usage_events": 12,
        "earliest_usage": "2025-01-02T10:30:00.000Z",
        "latest_usage": "2025-01-28T14:15:00.000Z",
        "billing_entity_id": "folder-id-123",
        "billing_entity_name": "My Project Folder",
        "billing_entity_type": "folder"
    }
]
```

| Field                 | Type   | Description                                                                    |
| --------------------- | ------ | ------------------------------------------------------------------------------ |
| `api_key_prefix`      | string | The first 5 characters of the API key associated with the usage                |
| `feature`             | string | The billing feature identifier (e.g., `"train"`, `"serverless-inference-run"`) |
| `total_credits_used`  | number | Total credits consumed for this key/feature combination                        |
| `usage_events`        | number | Count of individual usage events                                               |
| `earliest_usage`      | string | ISO timestamp of the first usage event in the range                            |
| `latest_usage`        | string | ISO timestamp of the last usage event in the range                             |
| `billing_entity_id`   | string | The folder ID or workspace ID that owns this usage                             |
| `billing_entity_name` | string | Human-readable name of the billing entity                                      |
| `billing_entity_type` | string | Either `"folder"` or `"workspace"`                                             |

#### Error Codes <a href="#error-codes" id="error-codes"></a>

| Status | Description                                                                      |
| ------ | -------------------------------------------------------------------------------- |
| `400`  | Billing Folders is not enabled for this workspace, or invalid request parameters |
| `401`  | Invalid or missing API key, or insufficient permissions                          |
| `423`  | The folder's usage is paused                                                     |
| `429`  | Rate limit exceeded (10 requests per minute)                                     |