Credits
An organization billed in credits pays for its runs in credits: each audience build, each scheduled refresh cycle, and each lookalike. The price of a run is known before it starts, and the run is charged when it is accepted. A run that fails, is cancelled, or completes with no results gets its credits back. Activations, cohorts, and size estimates carry no credits.
Credits answer only for an organization billed in credits. For any other
organization every endpoint on this page, and the two quotes on
Audiences, returns 403
with the message Credits are not enabled for your organization. (see
Errors), and credits_charged on an audience
is null. Ask your Account Manager about credits for your organization.
What reads credits:
- Get Credits returns the balance of the current month.
- Get Credits Statement lists what added credits and what used them in that month.
- Quote Audience and Quote Lookalike return the price of a run before you create it. Each takes the same body as its create. It creates nothing and is free.
- Every audience carries
credits_charged, the credits its run was charged after any refund, on Get Audience, List Audiences, the create responses, and theaudience.*webhooks. - Get Usage carries the same balance in its
creditsblock.
The balance and the statement require additional permissions which need to be approved by your Account Manager, the same as Usage. A quote needs only what its create needs.
The endpoints are authenticated and JSON-only. Send Authorization: Bearer <token> and Accept: application/json on every call. They use the read rate
bucket (120 requests/min per caller).
The period
Credits are counted over the current calendar month, in UTC, for every
organization, also during a contract term. used is what the month’s runs were
charged, net of their refunds. A refund counts with its run, in the month the
run was charged, so a refund of a run from an earlier month does not lower this
month’s used. available is what you can still spend now, including credits
from before the month (a top-up, for example). The share used is
used / (used + available), rounded down to one decimal, so it reads 100 only
when nothing is left.
state follows the share used:
state | When |
|---|---|
ok | Under 70% used. |
low | 70% or more used. |
critical | 90% or more used. |
out | Nothing left. |
Get Credits
GET /api/v2/credits
Returns your organization’s credits for the current month: the balance, the share used, the pace and the day the balance runs out at that pace, what expires next, and the credits used per run type and per user.
Auth: bearer token + Accept: application/json. Rate limit: read bucket
(120 requests/min).
curl "https://console.intuizi.com/api/v2/credits" \
-H "Authorization: Bearer <YOUR_TOKEN>" \
-H "Accept: application/json"Response
{
"status": "success",
"code": 200,
"message": "Resource fetched successfully.",
"data": {
"plan": "access",
"period": {
"type": "month",
"from": "2026-11-01",
"to": "2026-11-30",
"days": 30,
"days_elapsed": 2,
"percent_elapsed": 6.7
},
"available": 876,
"used": 124,
"percent_used": 12.4,
"state": "ok",
"threshold": null,
"expiring_next": null,
"expired": 0,
"pace": {
"credits_per_day": 62,
"runs_out_on": "2026-11-16",
"lasts_the_period": false
},
"by_operation": [
{ "operation_type": "lookalike", "label": "Lookalike", "credits": 120 },
{ "operation_type": "audience_build", "label": "Audience Build", "credits": 4 }
],
"by_user": [
{ "name": "Jane Doe", "credits": 124 }
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
plan | string or null | Your plan, for example access. null when none is recorded. |
period.type | string | Always month: the current calendar month, in UTC. |
period.from | string | First day of the month, as YYYY-MM-DD. |
period.to | string | Last day of the month, as YYYY-MM-DD. |
period.days | integer | Days in the month. |
period.days_elapsed | integer | Days of the month gone, today included. |
period.percent_elapsed | number | Share of the month gone, in percent, rounded to one decimal. |
available | integer | Credits you can spend now. |
used | integer | Credits the month’s runs were charged, net of their refunds. |
percent_used | number | used / (used + available) in percent, rounded down to one decimal. 100 only when nothing is left. |
state | string | ok, low, critical, or out, from the share used (see The period). |
threshold | integer or null | The highest alert level the share used reached: 70, 90, or 100. null under 70%. |
expiring_next | object or null | The next credits to expire: credits and expires_at (YYYY-MM-DD HH:MM:SS). null when nothing is due to expire. |
expired | integer | Credits that expired unused in the month. |
pace.credits_per_day | number | Credits used per day of the month so far. |
pace.runs_out_on | string or null | The day the balance runs out at that pace, as YYYY-MM-DD. null before any credits are used, or when nothing is left. |
pace.lasts_the_period | boolean | Whether the balance lasts to the end of the month at that pace. |
by_operation | array | Credits used per run type, most first: operation_type (audience_build, audience_refresh, or lookalike), its label, and credits. A run type with no credits is left out. |
by_user | array | Credits used per user of your organization, most first: name and credits. A user who has left your organization is listed as Former user. |
Get Credits Statement
GET /api/v2/credits/statement
Lists the current month’s entries, newest first: credits added (your plan, a top-up, credits from Intuizi), runs charged, refunds, and credits that expired. A run paid from two blocks of credits is one entry.
Auth: bearer token + Accept: application/json. Rate limit: read bucket
(120 requests/min).
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
search | string | No | Optional free-text filter: entries whose audience name or entry label contains it (case-insensitive). |
page | integer | No | Page number. Defaults to 1. |
per_page | integer | No | Entries per page, 1 to 100. Defaults to 25. |
curl "https://console.intuizi.com/api/v2/credits/statement?search=refund" \
-H "Authorization: Bearer <YOUR_TOKEN>" \
-H "Accept: application/json"Response
{
"status": "success",
"code": 200,
"message": "Resources fetched successfully.",
"data": {
"period": { "from": "2026-11-01", "to": "2026-11-30" },
"items": [
{
"id": 4,
"occurred_at": "2026-11-02T12:00:00+00:00",
"entry_type": "refund",
"entry": "Refund",
"audience": { "id": 90, "name": "Tea Drinkers" },
"user": "Jane Doe",
"credits": 4,
"note": "Run failed (status 403)"
},
{
"id": 3,
"occurred_at": "2026-11-02T11:00:00+00:00",
"entry_type": "debit",
"entry": "Audience Build",
"audience": { "id": 90, "name": "Tea Drinkers" },
"user": "Jane Doe",
"credits": -4,
"note": null
},
{
"id": 1,
"occurred_at": "2026-11-01T00:00:00+00:00",
"entry_type": "grant",
"entry": "Plan credits",
"audience": null,
"user": null,
"credits": 1000,
"note": null
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total": 3,
"last_page": 1
}
}
}Response fields
| Field | Type | Description |
|---|---|---|
period.from | string | First day of the month the statement covers, as YYYY-MM-DD. |
period.to | string | Last day of that month, as YYYY-MM-DD. |
items[].id | integer | The entry id. |
items[].occurred_at | string | When the entry counts, in ISO 8601 (UTC). A grant is dated when its credits can first be spent: a month’s Plan credits at 00:00 on the 1st, or on the first day of the term. An expiry is dated at the last second of the credits’ last day (23:59:59), so the expiry of a month’s plan credits falls in that month. When a refund gives back credits that had already expired, they expire again, and that expiry is dated when it is written. Every other entry is dated when it is written. |
items[].entry_type | string | grant (credits added), debit (a run charged), refund, expiry (credits that expired), or adjustment. |
items[].entry | string | What the entry is, as the console labels it, for example Plan credits, Top-up, Audience Build, Scheduled Refresh, Lookalike, Refund, or Expired. |
items[].audience | object or null | The audience of a run: id and name. null for entries that are not a run. |
items[].user | string or null | The user of your organization the entry belongs to, or Former user for one who has left it. null for an entry with no user, such as credits added. |
items[].credits | integer | The signed credits: positive when credits were added or given back, negative when used. |
items[].note | string or null | Why a refund was given, for example Run failed (status 403) or Completed with zero results. null on other entries. |
pagination | object | current_page, per_page, total, and last_page. |