Records and allowances

Allowances are counted in records, not requests. A record is one object in a response's data: an application, a condition, or a portfolio match.

Each record counts once a month

• The first time a record is returned to your account in a period, it uses one record.
• Returning the same record again in the same period is free, from any endpoint and any of your keys. Re-polling a page, or refreshing an application you already fetched this month, costs nothing.
• An application and a condition are different records, even when they belong together.
• Empty responses, errors, /api/v1/authorities, /api/v1/usage and /api/v1/portfolio/sites use no records.
• One page holds at most 100 records, so a single request never uses more than 100.

Periods and resets

• Monthly allowances reset at 00:00 UTC on the 1st of each month. Unused records do not roll over, and the list of records you have already received starts again, so the first fetch of a record in a new month counts again.
• The free demo is 100 records for the life of the account. It never resets. Once it is used, choose a plan to carry on.
• Paid allowances on one account add up into one monthly pool: for example API Starter (2,500) plus the Leads website plan (1,000) gives 3,500 a month. Portfolio Monitor adds 2,000 a month for its endpoints.

Plans

Usage headers

Every successful response, and a records_exhausted error, carries these headers:

Or call GET /api/v1/usage (free) for the same figures as JSON.

When the allowance runs out

• Part-way through a page: you get the records that fit, plus a next_cursor that carries on from the last one returned. Records you already received this period are still included free.
• When not one new record fits: 429 with code records_exhausted. It is not a rate limit, so retrying will not help until the reset date in resets (or null on the demo) or until you upgrade.

HTTP/1.1 429 Too Many Requests
X-Records-Remaining: 0

{
  "error": "Your record allowance for this month has been used.",
  "code": "records_exhausted",
  "plan": "starter",
  "allowance": 2500,
  "used": 2500,
  "remaining": 0,
  "resets": "2026-11-01T00:00:00.000Z",
  "upgrade_url": "https://planningsignal.co.uk/developers#pricing"
}