Usage

Read your company’s data-scan usage for a calendar month: the total bytes scanned, a breakdown by operation type, your monthly limit block, and your organization’s live build budget. This is the same usage the console Usage tab shows. The month defaults to the current one and can be selected with the optional yearmonth parameter. No cost figures are exposed through the API.

Usage data requires additional permissions which need to be approved by your Account Manager.

The endpoint is authenticated and JSON-only. Send Authorization: Bearer <token> and Accept: application/json on the call. It uses the read rate bucket (120 requests/min per caller).

Get Usage

GET /api/v2/usage

Returns the usage for the authenticated user’s company for one calendar month. The month defaults to the current one. Pass yearmonth to read a past month instead. A token that is not attached to a company (for example an internal power-user token) receives an empty data payload.

Auth: bearer token + Accept: application/json. Rate limit: read bucket (120 requests/min).

Query parameters

Field	Type	Required	Description
`yearmonth`	string	No	The calendar month to report, as `YYYY-MM` (for example `2026-06`). Defaults to the current month. Must not be in the future and cannot be earlier than `2020-01`; an out-of-range or malformed value returns `422`. For any month other than the current one the `limit` block still reports your configured limit and the month’s used total, but `over_limit` and `percent_used` come back `null` (see the field notes below).

# Current month (default)
curl "https://console.intuizi.com/api/v2/usage" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

# A specific past month
curl "https://console.intuizi.com/api/v2/usage?yearmonth=2026-06" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

import requests

res = requests.get(
    "https://console.intuizi.com/api/v2/usage",
    params={"yearmonth": "2026-06"},  # omit for the current month
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
        "Accept": "application/json",
    },
)
usage = res.json()["data"]

// omit the query string for the current month
const res = await fetch("https://console.intuizi.com/api/v2/usage?yearmonth=2026-06", {
  headers: {
    Authorization: "Bearer <YOUR_TOKEN>",
    Accept: "application/json",
  },
});
const usage = (await res.json()).data;

Response

{
  "status": "success",
  "code": 200,
  "message": "Resource fetched successfully.",
  "data": {
    "yearmonth": "2026-07",
    "data_scanned": {
      "bytes": 5497558138880,
      "formatted": "5 TB"
    },
    "operations": [
      { "operation_type": "audience_build",   "label": "Audience Build",    "bytes": 3298534883328, "formatted": "3 TB" },
      { "operation_type": "audience_refresh", "label": "Scheduled Refresh", "bytes": 0,             "formatted": "0 B"  },
      { "operation_type": "lookalike",        "label": "Lookalike",         "bytes": 1099511627776, "formatted": "1 TB" },
      { "operation_type": "cohort",           "label": "Cohort",            "bytes": 0,             "formatted": "0 B"  },
      { "operation_type": "activation",       "label": "Activation",        "bytes": 1099511627776, "formatted": "1 TB" },
      { "operation_type": "estimate",         "label": "Size Estimate",     "bytes": 0,             "formatted": "0 B"  }
    ],
    "limit": {
      "data_scan_limit_bytes": 10995116277760,
      "data_scan_limit_formatted": "10 TB",
      "enforced": true,
      "used_bytes": 5497558138880,
      "used_formatted": "5 TB",
      "percent_used": 50.0,
      "over_limit": false
    },
    "build_budget": {
      "enforced": true,
      "per_hour": 60,
      "per_day": 300,
      "used_last_hour": 3,
      "used_last_day": 12,
      "retry_after_seconds": null
    }
  }
}

Response fields

Field	Type	Description
`yearmonth`	string	The calendar month the figures cover, as `YYYY-MM`. Echoes the requested month (or the current month when `yearmonth` was omitted).
`data_scanned.bytes`	integer	Total bytes scanned across all operations this month.
`data_scanned.formatted`	string	The same total as a human-readable string (for example `5 TB`).
`operations`	array	Per-operation-type breakdown. Always contains all six operation types, in a stable order, so a type your company has not used this month appears with `0` bytes. New types are appended at the end; existing positions never move.
`operations[].operation_type`	string	One of `audience_build`, `audience_refresh`, `lookalike`, `cohort`, `activation`, `estimate`.
`operations[].label`	string	The human-readable operation name shown in the console.
`operations[].bytes`	integer	Bytes scanned by that operation type this month.
`operations[].formatted`	string	The same value as a human-readable string.
`limit.data_scan_limit_bytes`	integer or null	Your monthly data-scan limit in bytes. `null` means no limit is configured (unlimited).
`limit.data_scan_limit_formatted`	string or null	The limit as a human-readable string, or `null` when there is no limit.
`limit.enforced`	boolean	Whether the limit is actively enforced. When `false`, usage is tracked but not blocked.
`limit.used_bytes`	integer	Bytes used in the reported month (equal to `data_scanned.bytes`).
`limit.used_formatted`	string	The used amount as a human-readable string.
`limit.percent_used`	number or null	Percentage of the limit used, rounded to one decimal. `null` when there is no limit, and `null` for any month other than the current one (the limit is a live figure, so it is not applied to a past month).
`limit.over_limit`	boolean or null	Whether the reported month’s usage has exceeded the limit. `false` when there is no limit, and `null` for any month other than the current one.
`build_budget.enforced`	boolean	Whether your organization’s build budget is enforced. When `false`, the counts are still reported but creates are not refused. Separate from `limit.enforced`.
`build_budget.per_hour`	integer	Worker-bound creates allowed per rolling hour.
`build_budget.per_day`	integer	Worker-bound creates allowed per rolling 24 hours.
`build_budget.used_last_hour`	integer	Creates counted in the last 60 minutes. Scheduled replays are not counted, and deleted resources still are.
`build_budget.used_last_day`	integer	Creates counted in the last 24 hours, counted the same way.
`build_budget.retry_after_seconds`	integer or null	When the budget is enforced and a window is used up, the seconds until every used-up window has a free slot (at least 1). `null` otherwise.

What counts as usage

Usage is measured as the number of bytes scanned when your operations run. Each operation type maps to an action you take through the API or the console:

Operation type	Counts the bytes scanned when you…
`audience_build`	Build an audience.
`audience_refresh`	Run a scheduled refresh of an existing audience.
`lookalike`	Build a lookalike audience.
`cohort`	Import a cohort from a cloud file.
`activation`	Activate an audience to a destination.
`estimate`	Run an audience size estimate. The estimate runs the same build as a create, so it scans the same data.

Figures reset at the start of each calendar month. Cost is intentionally not part of this response - talk to your Account Manager for billing detail.

Common Webhooks