Get usage (v2)
Retrieves usage metrics for specified customer workspaces within a defined time frame, including task usage, recipe counts, and counts of successful and failed jobs. This endpoint parses and returns datetime values in the Embedded admin's workspace timezone.
<Tip title="QUERY USAGE FOR MULTIPLE WORKSPACES IN A SINGLE REQUEST"> We recommend querying usage for all relevant workspaces in a single request to optimize performance.</Tip>
<Note title="JOB COUNTING AND ALLOCATION"> Each unique job run is counted only once. Jobs are never double-counted but may be allocated differently depending on the query timeframe, interval, and the most recent retry.</Note>
<Warning title="INCLUDE USAGE METRICS FOR DELETED RECIPES"> To include metrics for deleted recipes in the response, provide only the following fields in the request body: **from**, **to**, **workspace_ids** or **external_ids**, and **interval** (optional). Including any additional fields limits the usage data to non-deleted recipes that match those conditions.</Warning>
Headers
Authorization
Bearer authentication of the form Bearer <token>, where token is your auth token.
Query parameters
from
Start of the time range for retrieving usage metrics, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ).
to
End of the time range for retrieving usage metrics, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ).
interval
Sets the time interval for aggregating results. Accepted values: none, year, month, week, day, hour. Default is none.
workspace_ids
Customer workspace IDs to retrieve usage data for. Required if external_ids is not provided.
external_ids
Customer external IDs to retrieve usage data for. Required if workspace_ids is not provided.
recipe_name_pattern
Filters results by recipes matching the specified name pattern (for example, `[TEST] Recipe`). Case-sensitive. This filter returns any recipe with a name that contains the specified pattern. For example, both DeVelopment and MedveDeV would match the pattern DeV. The filters accept patterns with three or more characters. Do not provide if using `recipe_ids[]`. Wildcards and regular expressions are not supported.
folder_name_pattern
Filters results by folders matching the specified name pattern (for example, `[PROD] Folder`). Case-sensitive. This filter returns any folder with a name that contains the specified pattern. For example, both DeVelopment and MedveDeV would match the pattern DeV. The filters accept patterns with three or more characters. Do not provide if using `folder_ids[]`. Wildcards and regular expressions are not supported.
group_by
Specifies how results should be grouped. Accepted values: recipe, workspace. Default is workspace.
Allowed values:
Response
Success - Usage metrics retrieved successfully.
data
An array containing usage metrics grouped by workspace or recipe.