Account and balance

Retrieve your account

GET /v1/account returns your account settings for the mode of the key you call with. It is also a quick way to check that a key works.

{
  "object": "account",
  "id": "acct_4Gh7Jk2Lm9",
  "name": "Example Learning Ltd",
  "livemode": true,
  "pricing": {
    "paper_credits_per_page": 1,
    "grading_credits_per_page": 1
  },
  "low_balance_threshold": 1000,
  "credits_valid_until": "2027-09-30T23:59:59Z",
  "technical_contact_email": "dev-team@example.com",
  "rate_limit_per_minute": 600
}

Field	Description
`pricing.paper_credits_per_page`	Credits per page for processing a paper.
`pricing.grading_credits_per_page`	Credits per page for grading a script.
`low_balance_threshold`	`credits.balance_low` is sent when your available balance falls below this.
`credits_valid_until`	When your current credits stop being usable, or `null` if they don’t expire. After it, your balance shows them as `expired` until we renew them.
`technical_contact_email`	Where we send operational notices, such as a disabled webhook endpoint. Ask us to change it.
`rate_limit_per_minute`	Your request limit in this mode.

In test mode, pricing shows your live rates, and credits_valid_until is null.

Retrieve your balance

GET /v1/balance

{
  "object": "balance",
  "livemode": true,
  "available": 9067,
  "held": 36,
  "expired": 0,
  "total": 9103
}

Field	Description
`available`	Credits you can use now.
`held`	Credits on hold for work in progress. See Holds.
`expired`	Credits past `credits_valid_until`. They are kept, not removed, and become available again when we renew them. Always `0` in test mode.
`total`	`available` + `held` + `expired`.

List credit transactions

GET /v1/credit_transactions lists every movement of credits. It takes the usual list parameters, plus type and source_id.

{
  "object": "list",
  "data": [
    {
      "id": "ctx_9Lm3Nb7Vc1",
      "object": "credit_transaction",
      "livemode": true,
      "type": "grading",
      "amount": -12,
      "balance_after": 9103,
      "pages": 12,
      "source": { "object": "submission", "id": "sub_7Hk2Pz9QaN" },
      "reference": null,
      "description": "Grading, 12 pages",
      "created_at": "2026-10-06T09:21:40Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Field	Type	Description
`type`	string	See below.
`amount`	integer	Credits added (positive) or removed (negative).
`balance_after`	integer	Your `total` balance just after this transaction.
`pages`	integer	The pages charged, for `paper_processing` and `grading`; otherwise `null`.
`source`	object	The paper or submission this transaction relates to, or `null`. It stays after you delete that paper or submission.
`reference`	string	For `top_up`, your invoice or payment reference; otherwise `null`.
`description`	string	A short description. For an `adjustment`, it says why.

`type`	`amount`	Meaning
`top_up`	positive	Credits you bought were added.
`paper_processing`	negative	A paper was read and moved to `awaiting_review`.
`grading`	negative	A submission was graded.
`adjustment`	either	A correction by our team, for example credits returned after a review. `source` is set when it concerns one paper or submission.
`expiry`	negative	Credits added with an end date of their own lapsed unused. The row can appear shortly after your balance drops. Reaching `credits_valid_until` isn’t a transaction: see `expired` on your balance.