Skip to content

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:

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:

stateWhen
okUnder 70% used.
low70% or more used.
critical90% or more used.
outNothing 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

FieldTypeDescription
planstring or nullYour plan, for example access. null when none is recorded.
period.typestringAlways month: the current calendar month, in UTC.
period.fromstringFirst day of the month, as YYYY-MM-DD.
period.tostringLast day of the month, as YYYY-MM-DD.
period.daysintegerDays in the month.
period.days_elapsedintegerDays of the month gone, today included.
period.percent_elapsednumberShare of the month gone, in percent, rounded to one decimal.
availableintegerCredits you can spend now.
usedintegerCredits the month’s runs were charged, net of their refunds.
percent_usednumberused / (used + available) in percent, rounded down to one decimal. 100 only when nothing is left.
statestringok, low, critical, or out, from the share used (see The period).
thresholdinteger or nullThe highest alert level the share used reached: 70, 90, or 100. null under 70%.
expiring_nextobject or nullThe next credits to expire: credits and expires_at (YYYY-MM-DD HH:MM:SS). null when nothing is due to expire.
expiredintegerCredits that expired unused in the month.
pace.credits_per_daynumberCredits used per day of the month so far.
pace.runs_out_onstring or nullThe 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_periodbooleanWhether the balance lasts to the end of the month at that pace.
by_operationarrayCredits 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_userarrayCredits 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

FieldTypeRequiredDescription
searchstringNoOptional free-text filter: entries whose audience name or entry label contains it (case-insensitive).
pageintegerNoPage number. Defaults to 1.
per_pageintegerNoEntries 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

FieldTypeDescription
period.fromstringFirst day of the month the statement covers, as YYYY-MM-DD.
period.tostringLast day of that month, as YYYY-MM-DD.
items[].idintegerThe entry id.
items[].occurred_atstringWhen 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_typestringgrant (credits added), debit (a run charged), refund, expiry (credits that expired), or adjustment.
items[].entrystringWhat the entry is, as the console labels it, for example Plan credits, Top-up, Audience Build, Scheduled Refresh, Lookalike, Refund, or Expired.
items[].audienceobject or nullThe audience of a run: id and name. null for entries that are not a run.
items[].userstring or nullThe 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[].creditsintegerThe signed credits: positive when credits were added or given back, negative when used.
items[].notestring or nullWhy a refund was given, for example Run failed (status 403) or Completed with zero results. null on other entries.
paginationobjectcurrent_page, per_page, total, and last_page.