API ReferenceTasksTasks

Fetch Usage Report

Retrieve usage statistics for task executions. This endpoint provides detailed usage data about task runs, including: - Number of executions over time, bucketed by hour (see `aggregation` below) - A per-revision breakdown alongside the combined `total_counts` - Optional filtering to only successful or only failed runs Use this data to: 1. Monitor task usage patterns 2. Track execution success rates 3. Analyze usage trends 4. Plan capacity and scaling **Aggregation window:** - `aggregation=day` (default): last 24 hours, bucketed hourly - `aggregation=week`: last 7 days, bucketed daily

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

OR
AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

org_idstringRequiredformat: "uuid"
The unique identifier of the organization.
project_idstringRequiredformat: "uuid"
The unique identifier of the project.
task_idstringRequiredformat: "uuid"
The specific Task to reference.

Query parameters

aggregationenumOptionalDefaults to day
The aggregation level for the report. Can be either 'day' or 'week'.
Allowed values:
statusenumOptional
Run outcome filter for the report. Can be ALL, SUCCESS, or FAIL.
Allowed values:

Response

Usage report retrieved successfully
task_idstringformat: "uuid"
The unique identifier of the Task.
date_rangemap from strings to any
The time range for the report, with start and end timestamps.
aggregationenum
The time interval for data aggregation. 'day' shows last 24 hours in hourly blocks, 'week' shows last 7 days in daily blocks.
statusenum
Run outcome filter applied to this usage report.
task_revisionslist of objects
Usage data broken down by task revision, showing invocation counts for each active revision.
total_countsmap from strings to integers
Total number of task invocations for each time interval across all revisions.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
500
Internal Server Error