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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/billing-folders-usage-report.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.