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:

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 ​

TypeResourceDescription
POST/api/v2/usage/billing_periodsRetrieve billing and credit context for the current billing period, including the metered and prepaid metrics for each workspace's plan.
POST/api/v2/usage/totalRetrieve credit totals for the current billing period, with metered and prepaid metric quantities and their credit usage.
POST/api/v2/usage/metrics_meteredRetrieve 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:

TypeResourceQuota
POSTRetrieve billing periods:
/api/v2/usage/billing_periods
30 requests per second
POSTRetrieve usage totals:
/api/v2/usage/total
5 requests per second
POSTRetrieve 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_periods

Payload ​

NameTypeDescription
scopestring enum (SELF, CHILDREN, ORGANIZATION)
optional
Determines which workspaces the request includes, relative to the requesting workspace. Defaults to SELF. Refer to Scopes.
workspace_idsarray 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.
limitinteger
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.
cursorstring
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
shell
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
shell
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
shell
curl -X POST https://YOUR_DATA_CENTER/api/v2/usage/billing_periods \
     -H "Authorization: Bearer <api_token>" \
     -H 'Content-Type: application/json' \
     -d '{}'

Response ​

NameTypeDescription
dataarrayBilling periods, one per workspace in scope.
data[].idstringThe billing period ID.
data[].workspace_idstringThe ID of the workspace the billing period belongs to.
data[].is_currentbooleanIndicates whether this is the workspace's current billing period.
data[].starts_atstringThe start of the billing period, as an ISO 8601 datetime in UTC.
data[].ends_atstringThe end of the billing period, as an ISO 8601 datetime in UTC.
data[].plan_namestringThe name of the workspace's plan.
data[].credit_limitintegerThe credit limit for the billing period.
data[].metrics_meteredarray of stringsThe metered metrics that apply to the billing period.
data[].metrics_prepaidarray of stringsThe prepaid metrics that apply to the billing period.
generated_atstringThe time the response was generated, as an ISO 8601 datetime in UTC.
scopestringThe scope the request used.
workspace_idsarray of stringsThe workspace_ids the request used, or null if the request didn't set it.
pagination.limitintegerThe page size the request used.
pagination.next_cursorstringThe cursor for the next page, or null on the last page.
AHQ workspace
json
{
  "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
json
{
  "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
json
{
  "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 by workspace_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/total

Payload ​

NameTypeDescription
scopestring 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_idsarray 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.
limitinteger
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.
cursorstring
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_bystring 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_sourcestring 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_periodstring 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 with scope: CHILDREN or scope: ORGANIZATION): Only the requesting workspace's row includes metrics_prepaid. Child rows omit the property instead of returning an empty object, because the requesting workspace's total already aggregates all child workspace consumption. With scope: CHILDREN and group_by: NONE, the combined row has no metrics_prepaid because that scope excludes the requesting workspace's row.
  • WORKSPACE: Each workspace row, including children, includes its own metrics_prepaid. Use this setting for chargeback or per-workspace visibility.
  • scope: SELF: A single-workspace request includes metrics_prepaid on its row, equivalent to WORKSPACE behavior.

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
shell
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
shell
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
shell
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 ​

NameTypeDescription
dataarrayResult rows. One row per workspace with group_by: WORKSPACE, or a single row with group_by: NONE.
data[].billing_period.idstringThe billing period ID. Not present with group_by: NONE.
data[].billing_period.is_currentbooleanIndicates whether this is the workspace's current billing period. Not present with group_by: NONE.
data[].workspace_idstringThe ID of the workspace the row belongs to. Not present with group_by: NONE.
data[].creditsstringThe sum of the credits for all of the row's metered and prepaid metrics.
data[].metrics_meteredobjectThe row's metered metrics, keyed by metric name. Each metric has a quantity and the credits that quantity costs.
data[].metrics_prepaidobjectThe 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.limitintegerThe page size the request used.
pagination.next_cursorstringThe cursor for the next page, or null on the last page.
scopestringThe scope the request used.
workspace_idsarray of stringsThe workspace_ids the request used, or null if the request didn't set it.
billing_period_sourcestringThe billing_period_source the request used, with the default applied if the request didn't set it.
billing_periodstringThe billing_period the request used. Only CURRENT.
group_bystringThe group_by the request used, with the default applied if the request didn't set it.
generated_atstringThe time the response was generated, as an ISO 8601 datetime in UTC.
AHQ workspace
json
{
  "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
json
{
  "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
json
{
  "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_metered

Payload ​

NameTypeDescription
scopestring 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_idsarray 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_idsarray 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.
limitinteger
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.
cursorstring
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_filtersobject
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_filtersobject
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.
metricsarray 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_bystring 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_sourcestring 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_periodstring enum (CURRENT)
optional
Accepts CURRENT only. Defaults to CURRENT.
timeframeobject
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.
granularitystring 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
shell
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
shell
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
shell
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 ​

NameTypeDescription
dataarrayUsage items, one per workspace, environment, or asset according to group_by. With granularity set, one item per time bucket.
data[].billing_period.idstringThe billing period ID.
data[].billing_period.is_currentbooleanIndicates whether this is the workspace's current billing period.
data[].workspace_idstringThe ID of the workspace the item belongs to.
data[].environment_idstringThe ID of the environment the item belongs to. Not present with group_by: WORKSPACE.
data[].interval.fromstringThe 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.tostringThe end of the item's aggregation window, as an ISO 8601 datetime in UTC.
data[].creditsstringThe credits for the item's metrics.
data[].metricsobjectThe item's metered metrics, keyed by metric name. Each metric has a quantity and the credits that quantity costs.
data[].assetobjectThe 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_idsobjectThe 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_idsobjectThe IDs of the asset's current project_id and folder_id. Omitted if the asset has no current project or folder.
data[].tagsarray of stringsThe asset's current tags. Omitted if the asset has no tags.
pagination.limitintegerThe page size the request used.
pagination.next_cursorstringThe cursor for the next page, or null on the last page.
timeframe.fromstringThe 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.tostringThe 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.fromstringThe start of the window the response covers, as an ISO 8601 datetime in UTC.
aligned_timeframe.tostringThe end of the window the response covers, as an ISO 8601 datetime in UTC.
granularitystringThe granularity the request used, or null.
scopestringThe scope the request used.
workspace_idsarray of stringsThe workspace_ids the request used, or null if the request didn't set it.
billing_period_sourcestringThe billing_period_source the request used, with the default applied if the request didn't set it.
billing_periodstringThe billing_period the request used. Only CURRENT.
group_bystringThe group_by the request used, with the default applied if the request didn't set it.
generated_atstringThe time the response was generated, as an ISO 8601 datetime in UTC.
AHQ workspace
json
{
  "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
json
{
  "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
json
{
  "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:

json
{
  "errors": [
    {
      "code": "WORKSPACE_ID_NOT_IN_SCOPE",
      "title": "One or more workspace_ids values aren't in the resolved scope."
    }
  ]
}
HTTP statusError codeReturned when
400ORG_SCOPE_REQUIRES_ADMINA Standard workspace requests scope: CHILDREN or scope: ORGANIZATION.
400WORKSPACE_ID_NOT_IN_SCOPEA workspace_ids entry isn't in the resolved scope.
400WORKSPACE_IDS_REQUIRES_ORG_SCOPEworkspace_ids is passed with scope: SELF. workspace_ids requires scope: CHILDREN or scope: ORGANIZATION.
400FILTER_SIZE_OUT_OF_BOUNDSworkspace_ids, environment_ids, metrics, or a current_filters/historical_filters array field exceeds its maximum number of entries.
400PROJECT_NOT_FOUNDA current_filters.project_ids entry references a missing or deleted project.
400FOLDER_NOT_FOUNDA current_filters.folder_ids entry references a missing or deleted folder.
400WORKSPACE_BILLING_NOT_READYThe workspace's billing period hasn't finished syncing yet.
400CROSS_PERIOD_NOT_SUPPORTEDMetered usage's timeframe crosses a billing period boundary.
400GRANULARITY_TOO_FINE_FOR_WINDOWMetered usage's granularity is too fine for the aligned window length. For example, MIN15 over a window of 2 or more days.
400INVALID_CURSORA cursor is malformed or doesn't match the query it was issued for.
400CURSOR_EXPIREDA cursor has expired.
400FILTER_SET_CHANGEDAn asset moved projects or was re-tagged between pages, so the assets that match current_filters changed. Restart from the first page.
401UNAUTHORIZEDThe requester isn't authorized to access the workspace.
403NOT_CREDIT_BASED_PLANThe requesting workspace doesn't measure usage with credits.
429NoneYour request exceeds the rate limits.
500USAGE_UNAVAILABLEUsage data couldn't be retrieved due to an internal error.

Last updated: