Skip to main content
GET
Workspace usage
Your API token must be allowed to use agents (use_agents), and you must have access to the workspace—the same layers as other agent and file API routes (Sanctum authentication, workspace access check).

Code Examples

Headers

integer
required
Workspace ID. Required as of 2026-09-01. Until then, if omitted, the user’s selected workspace is used (deprecated). After the cutoff, a missing header returns 422.

Query parameters

string
Relative window: 1d, 7d, or 30d. Ignored if both start_date and end_date are sent. If no date parameters are sent, the effective default is 30d.
date (YYYY-MM-DD)
Start of a custom range (inclusive). Required with end_date.
date (YYYY-MM-DD)
End of a custom range (inclusive). Must be greater than or equal to start_date. Required with start_date. The span cannot exceed 90 days; otherwise 422.
integer
Filter by the user who ran the agent. Without workspace permission to read other users’ activity, you only see your own executions; filtering by another user’s id returns 403.
string
Agent type filter: all, chat, image, text, voiceover, video, code. all or omitted means no type filter.
integer
Page number. Default 1, minimum 1.
integer
Page size. Default 20, between 1 and 100.
Date windows
  • With start_date + end_date: the inclusive range is capped at 90 days.
  • With range: the window is relative to the end of the current day (1d last 24 hours from that instant; 7d / 30d last seven or thirty calendar days from that end).
  • If the usage_history_min_date feature is enabled in app settings, the effective start of the range is not earlier than that date (silent clamp).
Caching
  • Listings are cached about 60 seconds per workspace, filters, and page. Identical requests within that window may return the same payload.

Response

Pagination uses has_more: the service requests per_page + 1 rows; if the extra row exists, has_more is true and only the first per_page items appear in items.

Item fields

Errors

Validation errors use the standard Laravel error payload; some workspace errors return JSON { "message": "..." } with a translated message.