Developer API - Usage and billing
Use the following endpoints to retrieve usage and billing data for workspaces that use credits to measure usage. Refer to the Billing and usage documentation for more information about billing.
AVAILABILITY
The usage and billing endpoints are only available for workspaces that measure usage with credits. Requests from workspaces that don't measure usage with credits return a 403 error.
This page covers the following endpoints:
- Retrieve billing periods: Returns your plan, credit limit, billing period, and metrics that apply to your workspace.
- Retrieve usage totals: Returns credits consumed in the selected billing period.
- Retrieve metered usage: Returns runtime usage by workspace, environment, or asset, with an optional time series.
CREDITS AND QUANTITIES
credits values are decimal strings, not JSON numbers. For example, "11.2". Trailing zeros are removed, so a whole number has no decimal point. For example, "20". quantity values are integers.
Quick reference
| Type | Resource | Description |
|---|---|---|
| POST | /api/v2/usage/billing_periods | Retrieve billing and credit context for the current billing period, including the metered and prepaid metrics for each workspace's plan. |
| POST | /api/v2/usage/total | Retrieve credit totals for the current billing period, with metered and prepaid metric quantities and their credit usage. |
| POST | /api/v2/usage/metrics_metered | Retrieve metered runtime usage as time series data or per-asset totals. Excludes prepaid metrics. |
Rate limits
Usage and billing resources have the following rate limits:
| Type | Resource | Quota |
|---|---|---|
| POST | Retrieve billing periods: /api/v2/usage/billing_periods | 30 requests per second |
| POST | Retrieve usage totals: /api/v2/usage/total | 5 requests per second |
| POST | Retrieve metered usage: /api/v2/usage/metrics_metered | 5 requests per second |
Scopes
Workato uses scopes to limit which workspaces a request can access and what data it returns. Most standard workspaces use the default scope, SELF.
The usage and billing endpoints have the following scopes:
SELF(default): The requesting workspace only.CHILDREN: The requesting workspace's child workspaces, excluding the requesting workspace. Available to Embedded and Automation HQ (AHQ) workspaces only.ORGANIZATION: The requesting workspace and its child workspaces. Available to Embedded and AHQ workspaces only.
Retrieve billing periods
This endpoint returns billing context, including plan, credit limit, and metrics for each workspace's current billing period. It doesn't return consumed credits. Use the usage totals endpoint to retrieve consumed credits.
POST https://YOUR_DATA_CENTER/api/v2/usage/billing_periodsPayload
| Name | Type | Description |
|---|---|---|
| scope | string enum (SELF, CHILDREN, ORGANIZATION)optional | Determines which workspaces the request includes, relative to the requesting workspace. Defaults to SELF. Refer to Scopes. |
| workspace_ids | array of strings optional | Narrows a CHILDREN or ORGANIZATION request to specific workspaces. Accepts 1 to 100 entries. Omit this parameter, or pass null, to include every workspace in the scope. A deleted child workspace remains in scope until it's purged. |
| limit | integer optional | The maximum number of billing periods to return per page. Defaults to 100. Values above 1000 are set to 1000. Values of 0 or below, and non-numeric values, are set to 100. |
| cursor | string optional | Pass the previous response's pagination.next_cursor value, with the same parameters you used for that page, to request the next page. Treat the cursor as an opaque value because its format can change. |
Sample request
AHQ workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/billing_periods \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "ORGANIZATION"
}'Embedded workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/billing_periods \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "CHILDREN",
"workspace_ids": ["325688"]
}'Standard workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/billing_periods \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{}'Response
| Name | Type | Description |
|---|---|---|
| data | array | Billing periods, one per workspace in scope. |
| data[].id | string | The billing period ID. |
| data[].workspace_id | string | The ID of the workspace the billing period belongs to. |
| data[].is_current | boolean | Indicates whether this is the workspace's current billing period. |
| data[].starts_at | string | The start of the billing period, as an ISO 8601 datetime in UTC. |
| data[].ends_at | string | The end of the billing period, as an ISO 8601 datetime in UTC. |
| data[].plan_name | string | The name of the workspace's plan. |
| data[].credit_limit | integer | The credit limit for the billing period. |
| data[].metrics_metered | array of strings | The metered metrics that apply to the billing period. |
| data[].metrics_prepaid | array of strings | The prepaid metrics that apply to the billing period. |
| generated_at | string | The time the response was generated, as an ISO 8601 datetime in UTC. |
| scope | string | The scope the request used. |
| workspace_ids | array of strings | The workspace_ids the request used, or null if the request didn't set it. |
| pagination.limit | integer | The page size the request used. |
| pagination.next_cursor | string | The cursor for the next page, or null on the last page. |
AHQ workspace
{
"data": [
{
"id": "accp-AbLzCDBQ-34NtGh-B6",
"workspace_id": "325606",
"is_current": true,
"starts_at": "2026-08-25T20:11:34.814Z",
"ends_at": "2027-08-25T20:11:34.814Z",
"plan_name": "Workato ONE",
"credit_limit": 100000,
"metrics_metered": [
"tasks",
"api_calls",
"idp_pages_processed",
"events_processed",
"rows_consumed",
"agent_actions",
"mcp_tool_calls"
],
"metrics_prepaid": [
"workflow_app_seats",
"go_seats",
"knowledge_storage_gb"
]
},
{
"id": "accp-AbMWfefE-arcBww-B6",
"workspace_id": "325685",
"is_current": true,
"starts_at": "2026-08-25T20:11:34.814Z",
"ends_at": "2027-08-25T20:11:34.814Z",
"plan_name": "Workato ONE",
"credit_limit": 200,
"metrics_metered": [
"tasks",
"api_calls",
"idp_pages_processed",
"events_processed",
"rows_consumed",
"agent_actions",
"mcp_tool_calls"
],
"metrics_prepaid": [
"workflow_app_seats",
"go_seats",
"knowledge_storage_gb"
]
}
],
"generated_at": "2026-11-02T21:23:24.366473493Z",
"scope": "ORGANIZATION",
"workspace_ids": null,
"pagination": {
"limit": 100,
"next_cursor": null
}
}Embedded workspace
{
"data": [
{
"id": "accp-AbMWnhPT-FBQghY-B6",
"workspace_id": "325688",
"is_current": true,
"starts_at": "2026-08-26T20:48:37.269Z",
"ends_at": "2027-08-26T20:48:37.269Z",
"plan_name": "Workato ONE",
"metrics_metered": [
"tasks",
"api_calls",
"idp_pages_processed",
"events_processed",
"rows_consumed",
"agent_actions",
"mcp_tool_calls"
],
"metrics_prepaid": [
"workflow_app_seats",
"go_seats",
"knowledge_storage_gb"
]
}
],
"generated_at": "2026-11-02T21:23:24.863710474Z",
"scope": "CHILDREN",
"workspace_ids": [
"325688"
],
"pagination": {
"limit": 100,
"next_cursor": null
}
}Standard workspace
{
"data": [
{
"id": "accp-AbLxzbNa-rfoTDH-B6",
"workspace_id": "325603",
"is_current": true,
"starts_at": "2026-08-25T20:00:13.722Z",
"ends_at": "2027-08-25T20:00:13.722Z",
"plan_name": "Workato ONE",
"credit_limit": 1000000,
"metrics_metered": [
"tasks",
"api_calls",
"idp_pages_processed",
"events_processed",
"rows_consumed",
"agent_actions",
"mcp_tool_calls"
],
"metrics_prepaid": [
"workflow_app_seats",
"go_seats",
"knowledge_storage_gb"
]
}
],
"generated_at": "2026-11-02T21:23:25.308570066Z",
"scope": "SELF",
"workspace_ids": null,
"pagination": {
"limit": 100,
"next_cursor": null
}
}Billing periods scopes
Billing periods returns the following billing periods for each scope:
SELF: The requester's billing period.CHILDREN: All child workspace billing periods, optionally narrowed byworkspace_ids.ORGANIZATION: The requester's billing period and its child workspace billing periods.
The billing periods endpoint lists every workspace in scope. The usage totals endpoint with group_by: WORKSPACE and the metered usage endpoint omit workspaces with no usage. A child workspace that appears in billing periods can have no rows in those endpoints.
Retrieve usage totals
This endpoint returns total credits for the current billing period, with the quantity and credit usage for each metric. The credit usage for each row sums its metered and prepaid metrics. It reports total credit consumption to date and doesn't have a time-based filter.
POST https://YOUR_DATA_CENTER/api/v2/usage/totalPayload
| Name | Type | Description |
|---|---|---|
| scope | string enum (SELF, CHILDREN, ORGANIZATION)optional | Determines which workspaces the request includes, relative to the requesting workspace. Defaults to SELF. Refer to Scopes. A Standard workspace can only omit scope or pass SELF. Passing CHILDREN or ORGANIZATION from a Standard workspace returns 400 ORG_SCOPE_REQUIRES_ADMIN. |
| workspace_ids | array of strings optional | Narrows a CHILDREN or ORGANIZATION request to specific workspaces. Accepts 1 to 100 entries. Omit this parameter, or pass null, to include every workspace in the scope. Every ID must belong to a workspace in the scope. A deleted child workspace remains in scope until it's purged. An ID for a purged or nonexistent workspace or the requester's own ID with scope: CHILDREN returns 400 WORKSPACE_ID_NOT_IN_SCOPE. Passing workspace_ids with scope: SELF returns 400 WORKSPACE_IDS_REQUIRES_ORG_SCOPE. |
| limit | integer optional | The maximum number of rows to return per page. Defaults to 100. Values above 1000 are set to 1000. Values of 0 or below, and non-numeric values, are set to 100. |
| cursor | string optional | Pass the previous response's pagination.next_cursor value, with the same parameters you used for that page, to request the next page. You can change limit between pages. A malformed cursor, or a cursor from a different query, returns 400 INVALID_CURSOR. An expired cursor returns 400 CURSOR_EXPIRED. Treat the cursor as an opaque value because its format can change. |
| group_by | string enum (WORKSPACE, NONE)optional | The dimension used to break down result rows. WORKSPACE returns one row per workspace. NONE returns one row for the whole query, combined across workspaces, with no workspace_id or billing_period on that row. Defaults to NONE. WORKSPACE omits workspaces with no usage. NONE returns its single row. NONE with scope: ORGANIZATION sums metrics_metered across every workspace in scope. metrics_prepaid reports the requesting workspace's pooled figure, which already includes its children's prepaid usage, so children aren't added again. |
| billing_period_source | string enum (ORGANIZATION, WORKSPACE)optional | Determines which billing period is used when scope includes more than one workspace. Defaults to WORKSPACE with scope: SELF and ORGANIZATION with scope: CHILDREN or scope: ORGANIZATION. |
| billing_period | string enum (CURRENT)optional | Accepts CURRENT only. Defaults to CURRENT. |
PREPAID METRICS AND BILLING PERIOD SOURCE
The billing_period_source parameter determines whether responses include metrics_prepaid:
ORGANIZATION(the default withscope: CHILDRENorscope: ORGANIZATION): Only the requesting workspace's row includesmetrics_prepaid. Child rows omit the property instead of returning an empty object, because the requesting workspace's total already aggregates all child workspace consumption. Withscope: CHILDRENandgroup_by: NONE, the combined row has nometrics_prepaidbecause that scope excludes the requesting workspace's row.WORKSPACE: Each workspace row, including children, includes its ownmetrics_prepaid. Use this setting for chargeback or per-workspace visibility.scope: SELF: A single-workspace request includesmetrics_prepaidon its row, equivalent toWORKSPACEbehavior.
billing_period_source doesn't affect metrics_metered. Every row includes it as a per-workspace sum, because metered usage belongs to the workspace that generated it.
Sample request
AHQ workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/total \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "ORGANIZATION",
"group_by": "WORKSPACE",
"billing_period_source": "ORGANIZATION",
"billing_period": "CURRENT"
}'Embedded workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/total \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "CHILDREN",
"workspace_ids": ["325688"],
"group_by": "WORKSPACE",
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT"
}'Standard workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/total \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "SELF",
"group_by": "WORKSPACE",
"billing_period": "CURRENT"
}'Response
| Name | Type | Description |
|---|---|---|
| data | array | Result rows. One row per workspace with group_by: WORKSPACE, or a single row with group_by: NONE. |
| data[].billing_period.id | string | The billing period ID. Not present with group_by: NONE. |
| data[].billing_period.is_current | boolean | Indicates whether this is the workspace's current billing period. Not present with group_by: NONE. |
| data[].workspace_id | string | The ID of the workspace the row belongs to. Not present with group_by: NONE. |
| data[].credits | string | The sum of the credits for all of the row's metered and prepaid metrics. |
| data[].metrics_metered | object | The row's metered metrics, keyed by metric name. Each metric has a quantity and the credits that quantity costs. |
| data[].metrics_prepaid | object | The row's prepaid metrics, keyed by metric name. Each metric has a quantity and the credits that quantity costs. Whether it's included depends on billing_period_source. Refer to the Payload table. |
| pagination.limit | integer | The page size the request used. |
| pagination.next_cursor | string | The cursor for the next page, or null on the last page. |
| scope | string | The scope the request used. |
| workspace_ids | array of strings | The workspace_ids the request used, or null if the request didn't set it. |
| billing_period_source | string | The billing_period_source the request used, with the default applied if the request didn't set it. |
| billing_period | string | The billing_period the request used. Only CURRENT. |
| group_by | string | The group_by the request used, with the default applied if the request didn't set it. |
| generated_at | string | The time the response was generated, as an ISO 8601 datetime in UTC. |
AHQ workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbLzCDBQ-34NtGh-B6",
"is_current": true
},
"workspace_id": "325685",
"credits": "31356.9021",
"metrics_metered": {
"agent_actions": {
"quantity": 50,
"credits": "1000"
},
"api_calls": {
"quantity": 586,
"credits": "232.25"
},
"events_processed": {
"quantity": 2042,
"credits": "367.56"
},
"idp_pages_processed": {
"quantity": 527,
"credits": "17549.1"
},
"mcp_tool_calls": {
"quantity": 33,
"credits": "1.65"
},
"rows_consumed": {
"quantity": 67663,
"credits": "453.3421"
},
"tasks": {
"quantity": 11753,
"credits": "11753"
}
}
},
{
"billing_period": {
"id": "accp-AbLzCDBQ-34NtGh-B6",
"is_current": true
},
"workspace_id": "325606",
"credits": "27291.3722",
"metrics_metered": {
"agent_actions": {
"quantity": 51,
"credits": "1020"
},
"api_calls": {
"quantity": 645,
"credits": "292.8"
},
"events_processed": {
"quantity": 2043,
"credits": "367.74"
},
"idp_pages_processed": {
"quantity": 610,
"credits": "20313"
},
"mcp_tool_calls": {
"quantity": 30,
"credits": "1.5"
},
"rows_consumed": {
"quantity": 36766,
"credits": "246.3322"
},
"tasks": {
"quantity": 5050,
"credits": "5050"
}
},
"metrics_prepaid": {
"workflow_app_seats": {
"quantity": 10,
"credits": "0"
},
"go_seats": {
"quantity": 1000,
"credits": "0"
},
"knowledge_storage_gb": {
"quantity": 1024,
"credits": "0"
}
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"scope": "ORGANIZATION",
"workspace_ids": null,
"billing_period_source": "ORGANIZATION",
"billing_period": "CURRENT",
"group_by": "WORKSPACE",
"generated_at": "2026-11-02T21:23:25.771276075Z"
}Embedded workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"credits": "36961.2705",
"metrics_metered": {
"agent_actions": {
"quantity": 50,
"credits": "1000"
},
"api_calls": {
"quantity": 608,
"credits": "222.55"
},
"events_processed": {
"quantity": 2041,
"credits": "367.38"
},
"idp_pages_processed": {
"quantity": 325,
"credits": "10822.5"
},
"mcp_tool_calls": {
"quantity": 25,
"credits": "1.25"
},
"rows_consumed": {
"quantity": 44715,
"credits": "299.5905"
},
"tasks": {
"quantity": 24248,
"credits": "24248"
}
},
"metrics_prepaid": {
"workflow_app_seats": {
"quantity": 0,
"credits": "0"
},
"go_seats": {
"quantity": 0,
"credits": "0"
},
"knowledge_storage_gb": {
"quantity": 0,
"credits": "0"
}
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"scope": "CHILDREN",
"workspace_ids": [
"325688"
],
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT",
"group_by": "WORKSPACE",
"generated_at": "2026-11-02T21:23:27.312270179Z"
}Standard workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"credits": "2210690.4663",
"metrics_metered": {
"agent_actions": {
"quantity": 76,
"credits": "1520"
},
"api_calls": {
"quantity": 1251,
"credits": "585"
},
"events_processed": {
"quantity": 5030,
"credits": "905.4"
},
"idp_pages_processed": {
"quantity": 3723,
"credits": "123975.9"
},
"mcp_tool_calls": {
"quantity": 67,
"credits": "2"
},
"rows_consumed": {
"quantity": 67189,
"credits": "450.1663"
},
"tasks": {
"quantity": 2083252,
"credits": "2083252"
}
},
"metrics_prepaid": {
"workflow_app_seats": {
"quantity": 10,
"credits": "0"
},
"go_seats": {
"quantity": 1000,
"credits": "0"
},
"knowledge_storage_gb": {
"quantity": 1024,
"credits": "0"
}
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"scope": "SELF",
"workspace_ids": null,
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT",
"group_by": "WORKSPACE",
"generated_at": "2026-11-02T21:23:28.318344605Z"
}Retrieve metered usage
This endpoint returns metered usage broken down by workspace, environment, or asset, including a time series when you set granularity. It paginates over usage items.
POST https://YOUR_DATA_CENTER/api/v2/usage/metrics_meteredPayload
| Name | Type | Description |
|---|---|---|
| scope | string enum (SELF, CHILDREN, ORGANIZATION)optional | Determines which workspaces the request includes, relative to the requesting workspace. Defaults to SELF. Refer to Scopes. A Standard workspace can only omit scope or pass SELF. Passing CHILDREN or ORGANIZATION from a Standard workspace returns 400 ORG_SCOPE_REQUIRES_ADMIN. |
| workspace_ids | array of strings optional | Narrows a CHILDREN or ORGANIZATION request to specific workspaces. Accepts 1 to 100 entries. Omit this parameter, or pass null, to include every workspace in the scope. Every ID must belong to a workspace in the scope. A deleted child workspace remains in scope until it's purged. An ID for a purged or nonexistent workspace or the requester's own ID with scope: CHILDREN returns 400 WORKSPACE_ID_NOT_IN_SCOPE. Passing workspace_ids with scope: SELF returns 400 WORKSPACE_IDS_REQUIRES_ORG_SCOPE. |
| environment_ids | array of strings optional | A flat list of environment IDs. Results must match these IDs and the filters in current_filters and historical_filters. Accepts 1 to 100 entries. |
| limit | integer optional | The maximum number of usage items to return per page. Defaults to 100. Values above 1000 are set to 1000. Values of 0 or below, and non-numeric values, are set to 100. |
| cursor | string optional | Pass the previous response's pagination.next_cursor value, with the same parameters you used for that page, to request the next page. You can change limit between pages. A malformed cursor, or a cursor from a different query, returns 400 INVALID_CURSOR. An expired cursor returns 400 CURSOR_EXPIRED. Treat the cursor as an opaque value because its format can change. |
| current_filters | object optional | Filters on an asset's current project, folder, and tags. A row must match every field you provide. |
| current_filters[project_ids] | array of strings optional | Accepts 1 to 100 entries. A missing or deleted project returns 400 PROJECT_NOT_FOUND. |
| current_filters[folder_ids] | array of strings optional | Accepts 1 to 100 entries. A missing or deleted folder returns 400 FOLDER_NOT_FOUND. |
| current_filters[tags] | array of strings optional | Free-form tag strings. Accepts 1 to 100 entries. A tag that doesn't exist matches no rows. |
| historical_filters | object optional | Filters on the asset recorded with the usage. A row must match at least one field you provide. |
| historical_filters[recipe_ids] | array of strings optional | Accepts 1 to 100 entries. Mutually exclusive with skill_ids. An ID that isn't a recipe, such as a skill's ID, matches no rows rather than returning unfiltered results. |
| historical_filters[skill_ids] | array of strings optional | Accepts 1 to 100 entries. Mutually exclusive with recipe_ids. |
| historical_filters[api_group_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[api_endpoint_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[mcp_server_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[data_pipeline_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[topic_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[agent_ids] | array of strings optional | Accepts 1 to 100 entries. |
| historical_filters[api_sub_features] | array of strings enum (managed_api, gateway)optional | Accepts up to 2 entries. Applies to api_endpoint usage. Adding this field alongside api_endpoint_ids broadens the result instead of narrowing it, because historical_filters fields combine with OR. |
| historical_filters[mcp_sub_features] | array of strings enum (managed, proxy)optional | Accepts up to 2 entries. Applies to mcp_server usage. Adding this field alongside mcp_server_ids broadens the result instead of narrowing it, because historical_filters fields combine with OR. |
| metrics | array of strings enum (tasks, business_actions, api_calls, idp_pages_processed, events_processed, rows_consumed, agent_actions, mcp_tool_calls)optional | The metered metrics to include. Accepts 1 to 8 entries, and an empty array isn't allowed. Omit this parameter, or pass null, to return all metered metrics. This endpoint doesn't return prepaid metrics. Refer to Pricing: Workflows (recipes) to learn how Workato calculates business actions. |
| group_by | string enum (WORKSPACE, ENVIRONMENT, ASSET)optional | The dimension used to break down result rows. WORKSPACE returns one row per workspace, without environment_id or asset. ENVIRONMENT returns one row per workspace and environment, without asset. ASSET returns one row per asset. Every row includes workspace_id and billing_period. Defaults to WORKSPACE. data omits any workspace, environment, or asset with no usage that matches the request's filters. |
| billing_period_source | string enum (ORGANIZATION, WORKSPACE)optional | Determines which billing period is used when scope includes more than one workspace. Defaults to WORKSPACE with scope: SELF and ORGANIZATION with scope: CHILDREN or scope: ORGANIZATION. ORGANIZATION anchors every row, including children, to the requesting workspace's current billing period, even where that crosses a child's own period boundary. WORKSPACE resolves each workspace's current billing period independently. |
| billing_period | string enum (CURRENT)optional | Accepts CURRENT only. Defaults to CURRENT. |
| timeframe | object optional | A sub-window within the current billing period. |
| timeframe[from] | string (ISO 8601 datetime, UTC) optional | The start of the window. Defaults to the start of the current billing period. |
| timeframe[to] | string (ISO 8601 datetime, UTC) optional | The end of the window. Defaults to the current time. Returns 400 CROSS_PERIOD_NOT_SUPPORTED if the window crosses a billing period boundary. |
| granularity | string enum (MIN15, HOUR, DAY, WEEK, MONTH)optional | The time bucket size for the result. Defaults to null, which applies no bucketing and returns one total over the window. MIN15 is allowed only when the aligned window is under 2 days, and HOUR only when it's under 1 week. Using MIN15 or HOUR outside those windows returns 400 GRANULARITY_TOO_FINE_FOR_WINDOW. DAY, WEEK, and MONTH are unrestricted. |
Sample request
AHQ workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/metrics_metered \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "ORGANIZATION",
"historical_filters": {
"mcp_sub_features": ["managed", "proxy"]
},
"group_by": "ASSET",
"billing_period_source": "ORGANIZATION",
"billing_period": "CURRENT",
"timeframe": {
"from": "2026-10-27T00:00:00Z",
"to": "2026-11-01T00:00:00Z"
},
"granularity": "DAY"
}'Embedded workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/metrics_metered \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "CHILDREN",
"workspace_ids": ["325688"],
"group_by": "ASSET",
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT",
"timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"granularity": "DAY"
}'Standard workspace
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/metrics_metered \
-H "Authorization: Bearer <api_token>" \
-H 'Content-Type: application/json' \
-d '{
"scope": "SELF",
"group_by": "ASSET",
"billing_period": "CURRENT",
"timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"granularity": "DAY"
}'Response
| Name | Type | Description |
|---|---|---|
| data | array | Usage items, one per workspace, environment, or asset according to group_by. With granularity set, one item per time bucket. |
| data[].billing_period.id | string | The billing period ID. |
| data[].billing_period.is_current | boolean | Indicates whether this is the workspace's current billing period. |
| data[].workspace_id | string | The ID of the workspace the item belongs to. |
| data[].environment_id | string | The ID of the environment the item belongs to. Not present with group_by: WORKSPACE. |
| data[].interval.from | string | The start of the item's aggregation window, as an ISO 8601 datetime in UTC. Each item includes this value even when granularity is omitted. |
| data[].interval.to | string | The end of the item's aggregation window, as an ISO 8601 datetime in UTC. |
| data[].credits | string | The credits for the item's metrics. |
| data[].metrics | object | The item's metered metrics, keyed by metric name. Each metric has a quantity and the credits that quantity costs. |
| data[].asset | object | The asset the usage belongs to, with its type and id. The type can be recipe, api_endpoint, mcp_server, or data_pipeline. A data_pipeline asset's id is a string such as dpr-AcCDWJ3e-MMzFAp-CD, not a number. Includes api_sub_feature or mcp_sub_feature for API endpoint and MCP server assets. Present with group_by: ASSET. |
| data[].historical_linked_entities_ids | object | The IDs of the entities linked to the usage when it happened, such as recipe_id, api_group_id, and api_endpoint_id. |
| data[].current_linked_entities_ids | object | The IDs of the asset's current project_id and folder_id. Omitted if the asset has no current project or folder. |
| data[].tags | array of strings | The asset's current tags. Omitted if the asset has no tags. |
| pagination.limit | integer | The page size the request used. |
| pagination.next_cursor | string | The cursor for the next page, or null on the last page. |
| timeframe.from | string | The timeframe.from value the request used. null if the request didn't set it, in which case the window starts at the start of the billing period. |
| timeframe.to | string | The timeframe.to value the request used. null if the request didn't set it, in which case the window ends at the current time. |
| aligned_timeframe.from | string | The start of the window the response covers, as an ISO 8601 datetime in UTC. |
| aligned_timeframe.to | string | The end of the window the response covers, as an ISO 8601 datetime in UTC. |
| granularity | string | The granularity the request used, or null. |
| scope | string | The scope the request used. |
| workspace_ids | array of strings | The workspace_ids the request used, or null if the request didn't set it. |
| billing_period_source | string | The billing_period_source the request used, with the default applied if the request didn't set it. |
| billing_period | string | The billing_period the request used. Only CURRENT. |
| group_by | string | The group_by the request used, with the default applied if the request didn't set it. |
| generated_at | string | The time the response was generated, as an ISO 8601 datetime in UTC. |
AHQ workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbLzCDBQ-34NtGh-B6",
"is_current": true
},
"workspace_id": "325685",
"environment_id": "325685",
"interval": {
"from": "2026-10-28T00:00:00Z",
"to": "2026-10-29T00:00:00Z"
},
"credits": "1.65",
"metrics": {
"mcp_tool_calls": {
"credits": "1.65",
"quantity": 33
}
},
"asset": {
"type": "mcp_server",
"id": "17038",
"mcp_sub_feature": "proxy"
},
"current_linked_entities_ids": {
"project_id": "558185",
"folder_id": "587664"
}
},
{
"billing_period": {
"id": "accp-AbLzCDBQ-34NtGh-B6",
"is_current": true
},
"workspace_id": "325606",
"environment_id": "325606",
"interval": {
"from": "2026-10-28T00:00:00Z",
"to": "2026-10-29T00:00:00Z"
},
"credits": "1.5",
"metrics": {
"mcp_tool_calls": {
"credits": "1.5",
"quantity": 30
}
},
"asset": {
"type": "mcp_server",
"id": "17037",
"mcp_sub_feature": "proxy"
},
"current_linked_entities_ids": {
"project_id": "558184",
"folder_id": "587663"
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"timeframe": {
"from": "2026-10-27T00:00:00Z",
"to": "2026-11-01T00:00:00Z"
},
"aligned_timeframe": {
"from": "2026-10-27T00:00:00Z",
"to": "2026-11-01T00:00:00Z"
},
"granularity": "DAY",
"scope": "ORGANIZATION",
"workspace_ids": null,
"billing_period_source": "ORGANIZATION",
"billing_period": "CURRENT",
"group_by": "ASSET",
"generated_at": "2026-11-02T21:35:43.928291352Z"
}Embedded workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"environment_id": "325688",
"interval": {
"from": "2026-08-26T21:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "36",
"metrics": {
"tasks": {
"credits": "36",
"quantity": 36
}
},
"asset": {
"type": "recipe",
"id": "1830039"
},
"current_linked_entities_ids": {
"project_id": "551651",
"folder_id": "576410"
}
},
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"environment_id": "325688",
"interval": {
"from": "2026-08-27T00:00:00Z",
"to": "2026-08-28T00:00:00Z"
},
"credits": "288",
"metrics": {
"tasks": {
"credits": "288",
"quantity": 288
}
},
"asset": {
"type": "recipe",
"id": "1830039"
},
"current_linked_entities_ids": {
"project_id": "551651",
"folder_id": "576410"
}
},
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"environment_id": "325688",
"interval": {
"from": "2026-08-28T00:00:00Z",
"to": "2026-08-29T00:00:00Z"
},
"credits": "288",
"metrics": {
"tasks": {
"credits": "288",
"quantity": 288
}
},
"asset": {
"type": "recipe",
"id": "1830039"
},
"current_linked_entities_ids": {
"project_id": "551651",
"folder_id": "576410"
}
},
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"environment_id": "325688",
"interval": {
"from": "2026-08-29T00:00:00Z",
"to": "2026-08-30T00:00:00Z"
},
"credits": "288",
"metrics": {
"tasks": {
"credits": "288",
"quantity": 288
}
},
"asset": {
"type": "recipe",
"id": "1830039"
},
"current_linked_entities_ids": {
"project_id": "551651",
"folder_id": "576410"
}
},
{
"billing_period": {
"id": "accp-AbMWnhPT-FBQghY-B6",
"is_current": true
},
"workspace_id": "325688",
"environment_id": "325688",
"interval": {
"from": "2026-08-30T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"credits": "288",
"metrics": {
"tasks": {
"credits": "288",
"quantity": 288
}
},
"asset": {
"type": "recipe",
"id": "1830039"
},
"current_linked_entities_ids": {
"project_id": "551651",
"folder_id": "576410"
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"aligned_timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"granularity": "DAY",
"scope": "CHILDREN",
"workspace_ids": [
"325688"
],
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT",
"group_by": "ASSET",
"generated_at": "2026-11-02T21:23:30.387751689Z"
}Standard workspace
{
"data": [
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "124",
"metrics": {
"tasks": {
"credits": "124",
"quantity": 124
}
},
"asset": {
"type": "recipe",
"id": "1829980"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "100",
"metrics": {
"tasks": {
"credits": "100",
"quantity": 100
}
},
"asset": {
"type": "recipe",
"id": "1830010"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "69.599999",
"metrics": {
"idp_pages_processed": {
"credits": "66.599999",
"quantity": 2
},
"tasks": {
"credits": "3",
"quantity": 3
}
},
"asset": {
"type": "recipe",
"id": "1830011"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576403"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "10",
"metrics": {
"tasks": {
"credits": "10",
"quantity": 10
}
},
"asset": {
"type": "recipe",
"id": "1829979"
},
"current_linked_entities_ids": {
"project_id": "551640",
"folder_id": "576385"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "5",
"metrics": {
"tasks": {
"credits": "5",
"quantity": 5
}
},
"asset": {
"type": "recipe",
"id": "1830040"
},
"current_linked_entities_ids": {
"project_id": "551640",
"folder_id": "576385"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-27T00:00:00Z"
},
"credits": "1",
"metrics": {
"tasks": {
"credits": "1",
"quantity": 1
}
},
"asset": {
"type": "recipe",
"id": "1829986"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-27T00:00:00Z",
"to": "2026-08-28T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1829980"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-27T00:00:00Z",
"to": "2026-08-28T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1830010"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-28T00:00:00Z",
"to": "2026-08-29T00:00:00Z"
},
"credits": "574",
"metrics": {
"tasks": {
"credits": "574",
"quantity": 574
}
},
"asset": {
"type": "recipe",
"id": "1829980"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-28T00:00:00Z",
"to": "2026-08-29T00:00:00Z"
},
"credits": "574",
"metrics": {
"tasks": {
"credits": "574",
"quantity": 574
}
},
"asset": {
"type": "recipe",
"id": "1830010"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-29T00:00:00Z",
"to": "2026-08-30T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1829980"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-29T00:00:00Z",
"to": "2026-08-30T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1830010"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-30T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1829980"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
},
{
"billing_period": {
"id": "accp-AbLxzbNa-rfoTDH-B6",
"is_current": true
},
"workspace_id": "325603",
"environment_id": "325603",
"interval": {
"from": "2026-08-30T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"credits": "576",
"metrics": {
"tasks": {
"credits": "576",
"quantity": 576
}
},
"asset": {
"type": "recipe",
"id": "1830010"
},
"current_linked_entities_ids": {
"project_id": "551641",
"folder_id": "576402"
}
}
],
"pagination": {
"limit": 100,
"next_cursor": null
},
"timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"aligned_timeframe": {
"from": "2026-08-26T00:00:00Z",
"to": "2026-08-31T00:00:00Z"
},
"granularity": "DAY",
"scope": "SELF",
"workspace_ids": null,
"billing_period_source": "WORKSPACE",
"billing_period": "CURRENT",
"group_by": "ASSET",
"generated_at": "2026-11-02T21:23:32.089247121Z"
}Error codes
Errors return an errors array. Each item has a code and a title describing the error. For example:
{
"errors": [
{
"code": "WORKSPACE_ID_NOT_IN_SCOPE",
"title": "One or more workspace_ids values aren't in the resolved scope."
}
]
}| HTTP status | Error code | Returned when |
|---|---|---|
| 400 | ORG_SCOPE_REQUIRES_ADMIN | A Standard workspace requests scope: CHILDREN or scope: ORGANIZATION. |
| 400 | WORKSPACE_ID_NOT_IN_SCOPE | A workspace_ids entry isn't in the resolved scope. |
| 400 | WORKSPACE_IDS_REQUIRES_ORG_SCOPE | workspace_ids is passed with scope: SELF. workspace_ids requires scope: CHILDREN or scope: ORGANIZATION. |
| 400 | FILTER_SIZE_OUT_OF_BOUNDS | workspace_ids, environment_ids, metrics, or a current_filters/historical_filters array field exceeds its maximum number of entries. |
| 400 | PROJECT_NOT_FOUND | A current_filters.project_ids entry references a missing or deleted project. |
| 400 | FOLDER_NOT_FOUND | A current_filters.folder_ids entry references a missing or deleted folder. |
| 400 | WORKSPACE_BILLING_NOT_READY | The workspace's billing period hasn't finished syncing yet. |
| 400 | CROSS_PERIOD_NOT_SUPPORTED | Metered usage's timeframe crosses a billing period boundary. |
| 400 | GRANULARITY_TOO_FINE_FOR_WINDOW | Metered usage's granularity is too fine for the aligned window length. For example, MIN15 over a window of 2 or more days. |
| 400 | INVALID_CURSOR | A cursor is malformed or doesn't match the query it was issued for. |
| 400 | CURSOR_EXPIRED | A cursor has expired. |
| 400 | FILTER_SET_CHANGED | An asset moved projects or was re-tagged between pages, so the assets that match current_filters changed. Restart from the first page. |
| 401 | UNAUTHORIZED | The requester isn't authorized to access the workspace. |
| 403 | NOT_CREDIT_BASED_PLAN | The requesting workspace doesn't measure usage with credits. |
| 429 | None | Your request exceeds the rate limits. |
| 500 | USAGE_UNAVAILABLE | Usage data couldn't be retrieved due to an internal error. |
Last updated: