Billing and usage

Operations tagged Billing and usage in the public API.

About Billing and usage

Read-only billing: what the account's plan grants, what it has used, and what it was charged. Changing the plan, buying add-ons or credit packs, and the Stripe billing portal stay in the dashboard — they end on Stripe-hosted pages only a person can complete — so there is no billing:write scope.

Message credits. Chat replies spend message credits. The plan grants a monthly allowance (credits.limit, null for unlimited): on a paid plan the month follows the billing cycle, on Free the calendar month. Purchased credits (credits.balance) never expire and are spent only once the allowance is used up. credits.remaining is what is left of both; at 0 a chat turn is refused with 402 MESSAGE_CREDITS_EXCEEDED. Test keys spend credits exactly like live keys. Subscribe to billing.credits.low and billing.credits.exhausted to be told before and when it happens.

Which call. GET /usage (identical to GET /billing/usage) is the meter to poll: credits and knowledge storage. GET /billing/subscription adds the plan in effect, its status, trial, renewal and cancellation dates, and agent and seat usage. GET /billing/plans is the self-service catalogue, and GET /billing/invoices the account's Stripe invoices.

IDs you will meet.

id on the usage and subscription objects — the account id.
A plan key (free, starter, standard, pro, …) — how a plan is named everywhere; Stripe price ids are never exposed.
Invoice id — Stripe's invoice id (in_…), the one string id of this group. No operation takes it.

/v1/billing/subscription

Retrieve the subscription

Returns the plan in effect and its state — status, billing interval, trial, renewal and cancellation dates, a downgrade scheduled for the period end — with usage against every plan limit: message credits, chatbots, knowledge storage and team seats. It reads what the dashboard's billing page reads, so the two never disagree. To poll only the credit meter, GET /usage is smaller.

Required scope: billing:read
Idempotency: Read-only
Rate limits

Responses

200
Success.
objectstringRequired
Alwaysbilling_subscription
idintegerRequired
The account id.
planobjectRequired
The plan in effect — paid, complimentary, on trial or Free.
statusstringRequired
The state of the plan in effect: free, complimentary (granted by Agentency), trialing, active, past_due, grace (cancelled, paid up until ends_at), canceled, or another Stripe subscription status (incomplete, incomplete_expired, unpaid, paused).
intervalstringnullableRequired
Billing interval of the paid subscription in effect; null when no paid subscription grants the plan (Free, complimentary, ended, paused).
Possible valuesmonthlyyearlynull
is_subscribedbooleanRequired
Whether a paid subscription grants the plan in effect.
is_compbooleanRequired
Whether the plan in effect is complimentary, granted by Agentency rather than paid for.
has_payment_issuebooleanRequired
Whether the Stripe subscription needs payment attention (past_due, unpaid, incomplete or paused), even while a complimentary plan is in effect.
on_trialbooleanRequired
Whether the plan in effect is a trial.
trial_ends_atstringnullableRequired
When the trial ends (ISO 8601); null without a trial.
cancel_at_period_endbooleanRequired
Whether the subscription is cancelled and runs until ends_at without renewing.
ends_atstringnullableRequired
When a cancelled subscription ends (ISO 8601); null while it renews.
renews_atstringnullableRequired
Next renewal of an active paid subscription (ISO 8601). null while cancelling, trialing, complimentary, or until the first billing period has synced.
comp_expires_atstringnullableRequired
When a complimentary plan ends (ISO 8601); null when it is permanent or not in effect.
pending_changeobjectnullableRequired
A downgrade scheduled for the end of the billing period; null when none. Undone in the dashboard.
pending_addon_changesarray of objectRequired
Recurring add-ons whose quantity drops at the end of the billing period; empty when none.
usageobjectRequired
Usage against every limit of the plan.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/billing/subscription' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "billing_subscription",
  "id": 1,
  "plan": {
    "key": "free",
    "name": "Free",
    "is_popular": false,
    "contact_sales": false,
    "price": {
      "monthly": 0,
      "yearly": 0
    },
    "purchasable": {
      "monthly": false,
      "yearly": false
    },
    "entitlements": {
      "message_credits": 50,
      "max_agents": 1,
      "kb_bytes_per_agent": 409600,
      "ai_actions_per_agent": 0,
      "instructions_per_agent": 1,
      "integrations_enabled": false,
      "website_embed_enabled": true,
      "team_seats": null,
      "ai_model_selection": false
    },
    "features": []
  },
  "status": "free",
  "interval": null,
  "is_subscribed": false,
  "is_comp": false,
  "has_payment_issue": false,
  "on_trial": false,
  "trial_ends_at": null,
  "cancel_at_period_end": false,
  "ends_at": null,
  "renews_at": null,
  "comp_expires_at": null,
  "pending_change": null,
  "pending_addon_changes": [],
  "usage": {
    "credits": {
      "used": 0,
      "limit": 50,
      "balance": 0,
      "remaining": 50
    },
    "agents": {
      "used": 2,
      "limit": 1,
      "extra": 0
    },
    "knowledge": {
      "per_agent_limit": 409600,
      "pool_limit": 0,
      "pool_used": 0,
      "extra_packs": 0
    },
    "seats": {
      "used": 1,
      "limit": null
    }
  }
}

/v1/billing/plans

List plans

The self-service catalogue, in display order and the same for every account: each plan's key, display price, the billing intervals a checkout accepts, its limits (entitlements) and feature keys. Plans are bought in the dashboard; Stripe price ids are never exposed.

Required scope: billing:read
Idempotency: Read-only
Rate limits

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of PlanResourceRequired
has_morebooleanRequired
next_cursoranynullableRequired
previous_cursoranynullableRequired
urlstringRequired
Always/v1/billing/plans
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/billing/plans' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "plan",
      "key": "free",
      "name": "Free",
      "is_popular": false,
      "is_free": true,
      "contact_sales": false,
      "price": {
        "monthly": 0,
        "yearly": 0
      },
      "purchasable_intervals": [],
      "entitlements": {
        "message_credits": 50,
        "max_agents": 1,
        "kb_bytes_per_agent": 409600,
        "ai_actions_per_agent": 0,
        "instructions_per_agent": 1,
        "integrations_enabled": false,
        "website_embed_enabled": true,
        "team_seats": null,
        "ai_model_selection": false
      },
      "features": []
    },
    {
      "object": "plan",
      "key": "starter",
      "name": "Starter",
      "is_popular": false,
      "is_free": false,
      "contact_sales": false,
      "price": {
        "monthly": 19,
        "yearly": 182
      },
      "purchasable_intervals": [],
      "entitlements": {
        "message_credits": 500,
        "max_agents": 2,
        "kb_bytes_per_agent": 10485760,
        "ai_actions_per_agent": 3,
        "instructions_per_agent": 3,
        "integrations_enabled": true,
        "website_embed_enabled": true,
        "team_seats": null,
        "ai_model_selection": true
      },
      "features": [
        "everything_free"
      ]
    },
    {
      "object": "plan",
      "key": "standard",
      "name": "Standard",
      "is_popular": true,
      "is_free": false,
      "contact_sales": false,
      "price": {
        "monthly": 99,
        "yearly": 950
      },
      "purchasable_intervals": [],
      "entitlements": {
        "message_credits": 4000,
        "max_agents": 5,
        "kb_bytes_per_agent": 20971520,
        "ai_actions_per_agent": 8,
        "instructions_per_agent": 8,
        "integrations_enabled": true,
        "website_embed_enabled": true,
        "team_seats": null,
        "ai_model_selection": true
      },
      "features": [
        "everything_starter"
      ]
    },
    {
      "object": "plan",
      "key": "pro",
      "name": "Pro",
      "is_popular": false,
      "is_free": false,
      "contact_sales": false,
      "price": {
        "monthly": 249,
        "yearly": 2390
      },
      "purchasable_intervals": [],
      "entitlements": {
        "message_credits": 15000,
        "max_agents": 10,
        "kb_bytes_per_agent": 41943040,
        "ai_actions_per_agent": 12,
        "instructions_per_agent": 12,
        "integrations_enabled": true,
        "website_embed_enabled": true,
        "team_seats": null,
        "ai_model_selection": true
      },
      "features": [
        "everything_standard"
      ]
    },
    {
      "object": "plan",
      "key": "agency",
      "name": "Agency",
      "is_popular": false,
      "is_free": false,
      "contact_sales": false,
      "price": {
        "monthly": 499,
        "yearly": 4790
      },
      "purchasable_intervals": [],
      "entitlements": {
        "message_credits": 50000,
        "max_agents": 30,
        "kb_bytes_per_agent": 62914560,
        "ai_actions_per_agent": 20,
        "instructions_per_agent": 20,
        "integrations_enabled": true,
        "website_embed_enabled": true,
        "team_seats": null,
        "ai_model_selection": true
      },
      "features": [
        "everything_pro"
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/billing/plans"
}

/v1/billing/usage

Retrieve usage

Returns the account's meter: message credits used and left this month, and knowledge storage against the plan allowance. GET /usage returns the same body at a shorter path.

Required scope: billing:read
Idempotency: Read-only
Rate limits

Responses

200
Success.
objectstringRequired
Alwaysbilling_usage
idintegerRequired
The account id.
planstringRequired
The key of the plan in effect (see GET /billing/plans).
creditsobjectRequired
Message credits this month.
knowledgeobjectRequired
Knowledge storage, counted in characters (1 character = 1 byte).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/billing/usage' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "billing_usage",
  "id": 1,
  "plan": "free",
  "credits": {
    "used": 0,
    "limit": 50,
    "balance": 0,
    "remaining": 50
  },
  "knowledge": {
    "per_agent_limit": 409600,
    "pool_limit": 0,
    "pool_used": 0,
    "extra_packs": 0
  }
}

/v1/billing/invoices

List invoices

The account's Stripe invoices, newest first, as a cursor list (limit, starting_after, ending_before); every status is included — filter on status client-side for paid ones. An account without a Stripe customer, or whose customer the billing account no longer knows, has an empty list. Each page is cached for a minute by default; a Stripe outage is 500 SERVER_ERROR, never an empty list.

Required scope: billing:read
Idempotency: Read-only
Rate limits

Query parameters

limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of InvoiceResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/billing/invoices
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesINVALID_CURSOR
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/billing/invoices' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "in_1QhExampleOpenInvoice",
      "total": "$19.00",
      "status": "open"
    },
    {
      "object": "invoice",
      "id": "in_1QfExamplePaidInvoice",
      "total": "$19.00",
      "status": "paid"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/billing/invoices"
}

/v1/usage

Retrieve usage at the short path

The meter of GET /billing/usage, at a top-level path: message credits used and left this month, and knowledge storage. Poll it to warn before credits run out, or subscribe to billing.credits.low and billing.credits.exhausted instead.

Required scope: billing:read
Idempotency: Read-only
Rate limits

Responses

200
Success.
objectstringRequired
Alwaysbilling_usage
idintegerRequired
The account id.
planstringRequired
The key of the plan in effect (see GET /billing/plans).
creditsobjectRequired
Message credits this month.
knowledgeobjectRequired
Knowledge storage, counted in characters (1 character = 1 byte).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/usage' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "billing_usage",
  "id": 1,
  "plan": "free",
  "credits": {
    "used": 0,
    "limit": 50,
    "balance": 0,
    "remaining": 50
  },
  "knowledge": {
    "per_agent_limit": 409600,
    "pool_limit": 0,
    "pool_used": 0,
    "extra_packs": 0
  }
}

About Billing and usage

IDs you will meet.

id on the usage and subscription objects — the account id.
A plan key (free, starter, standard, pro, …) — how a plan is named everywhere; Stripe price ids are never exposed.
Invoice id — Stripe's invoice id (in_…), the one string id of this group. No operation takes it.

{ "object": "billing_subscription", "id": 1, "plan": { "key": "free", "name": "Free", "is_popular": false, "contact_sales": false, "price": { "monthly": 0, "yearly": 0 }, "purchasable": { "monthly": false, "yearly": false }, "entitlements": { "message_credits": 50, "max_agents": 1, "kb_bytes_per_agent": 409600, "ai_actions_per_agent": 0, "instructions_per_agent": 1, "integrations_enabled": false, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": false }, "features": [] }, "status": "free", "interval": null, "is_subscribed": false, "is_comp": false, "has_payment_issue": false, "on_trial": false, "trial_ends_at": null, "cancel_at_period_end": false, "ends_at": null, "renews_at": null, "comp_expires_at": null, "pending_change": null, "pending_addon_changes": [], "usage": { "credits": { "used": 0, "limit": 50, "balance": 0, "remaining": 50 }, "agents": { "used": 2, "limit": 1, "extra": 0 }, "knowledge": { "per_agent_limit": 409600, "pool_limit": 0, "pool_used": 0, "extra_packs": 0 }, "seats": { "used": 1, "limit": null } } }

{ "object": "list", "data": [ { "object": "plan", "key": "free", "name": "Free", "is_popular": false, "is_free": true, "contact_sales": false, "price": { "monthly": 0, "yearly": 0 }, "purchasable_intervals": [], "entitlements": { "message_credits": 50, "max_agents": 1, "kb_bytes_per_agent": 409600, "ai_actions_per_agent": 0, "instructions_per_agent": 1, "integrations_enabled": false, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": false }, "features": [] }, { "object": "plan", "key": "starter", "name": "Starter", "is_popular": false, "is_free": false, "contact_sales": false, "price": { "monthly": 19, "yearly": 182 }, "purchasable_intervals": [], "entitlements": { "message_credits": 500, "max_agents": 2, "kb_bytes_per_agent": 10485760, "ai_actions_per_agent": 3, "instructions_per_agent": 3, "integrations_enabled": true, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": true }, "features": [ "everything_free" ] }, { "object": "plan", "key": "standard", "name": "Standard", "is_popular": true, "is_free": false, "contact_sales": false, "price": { "monthly": 99, "yearly": 950 }, "purchasable_intervals": [], "entitlements": { "message_credits": 4000, "max_agents": 5, "kb_bytes_per_agent": 20971520, "ai_actions_per_agent": 8, "instructions_per_agent": 8, "integrations_enabled": true, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": true }, "features": [ "everything_starter" ] }, { "object": "plan", "key": "pro", "name": "Pro", "is_popular": false, "is_free": false, "contact_sales": false, "price": { "monthly": 249, "yearly": 2390 }, "purchasable_intervals": [], "entitlements": { "message_credits": 15000, "max_agents": 10, "kb_bytes_per_agent": 41943040, "ai_actions_per_agent": 12, "instructions_per_agent": 12, "integrations_enabled": true, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": true }, "features": [ "everything_standard" ] }, { "object": "plan", "key": "agency", "name": "Agency", "is_popular": false, "is_free": false, "contact_sales": false, "price": { "monthly": 499, "yearly": 4790 }, "purchasable_intervals": [], "entitlements": { "message_credits": 50000, "max_agents": 30, "kb_bytes_per_agent": 62914560, "ai_actions_per_agent": 20, "instructions_per_agent": 20, "integrations_enabled": true, "website_embed_enabled": true, "team_seats": null, "ai_model_selection": true }, "features": [ "everything_pro" ] } ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/billing/plans" }

{ "object": "billing_usage", "id": 1, "plan": "free", "credits": { "used": 0, "limit": 50, "balance": 0, "remaining": 50 }, "knowledge": { "per_agent_limit": 409600, "pool_limit": 0, "pool_used": 0, "extra_packs": 0 } }

{ "object": "list", "data": [ { "object": "invoice", "id": "in_1QhExampleOpenInvoice", "total": "$19.00", "status": "open" }, { "object": "invoice", "id": "in_1QfExamplePaidInvoice", "total": "$19.00", "status": "paid" } ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/billing/invoices" }

About Billing and usage

/v1/billing/subscription

Responses

See also

Request

Response

/v1/billing/plans

Responses

See also

Request

Response

/v1/billing/usage

Responses

See also

Request

Response

/v1/billing/invoices

Query parameters

Responses

See also

Request

Response

/v1/usage

Responses

See also

Request

Response

About Billing and usage

/v1/billing/subscription

Responses

See also

Request

Response

/v1/billing/plans

Responses

See also

Request

Response

/v1/billing/usage

Responses

See also

Request

Response

/v1/billing/invoices

Query parameters

Responses

See also

Request

Response

/v1/usage

Responses

See also

Request

Response