# 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](/concepts/limits#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 ` and `Accept: application/json` on the call. It uses the read rate bucket (120 requests/min per caller). ## Get Usage {#get-apiv2usage} `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). | {{< tabs >}} {{< tab name="cURL" >}} ```bash # Current month (default) curl "https://console.intuizi.com/api/v2/usage" \ -H "Authorization: Bearer " \ -H "Accept: application/json" # A specific past month curl "https://console.intuizi.com/api/v2/usage?yearmonth=2026-06" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` {{< /tab >}} {{< tab name="Python" >}} ```python import requests res = requests.get( "https://console.intuizi.com/api/v2/usage", params={"yearmonth": "2026-06"}, # omit for the current month headers={ "Authorization": "Bearer ", "Accept": "application/json", }, ) usage = res.json()["data"] ``` {{< /tab >}} {{< tab name="JavaScript" >}} ```javascript // 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 ", Accept: "application/json", }, }); const usage = (await res.json()).data; ``` {{< /tab >}} {{< tab name="PHP" >}} ```php $res = Http::withToken('')->acceptJson() ->get('https://console.intuizi.com/api/v2/usage', ['yearmonth' => '2026-06']); $usage = $res->json('data'); ``` {{< /tab >}} {{< /tabs >}} ### Response ```json { "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](/concepts/limits#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](/api/v2/audiences). | | `audience_refresh` | Run a scheduled refresh of an existing audience. | | `lookalike` | Build a [lookalike audience](/api/v2/audiences#post-apiv2analysesaudiencescreate-lookalike). | | `cohort` | Import a [cohort](/api/v2/cohorts) from a cloud file. | | `activation` | [Activate](/api/v2/activations) an audience to a destination. | | `estimate` | Run an [audience size estimate](/api/v2/audiences#post-apiv2analysesaudiencesestimate). 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.