Billing Folders Usage Report

You can query billing folders usage data programmatically via the billing usage report API.

Endpoint

POST 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

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

Basic

Default is last 7 days, all features, all api keys.

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

Custom Date Range

Filter By Feature

All Parameters

Response Schema

The API returns a JSON array of usage records:

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

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)