Export a dataset as CSV or NDJSON (Pro and above)
The whole dataset — or a jurisdiction / status slice of it — as one file: every licence, every operator, or every domain ↔ operator link we hold. The same records the other endpoints serve; each row carries its own provenance (status_source_url, status_observed_at, last_listed_at), and for KH, TGC, IOM, ON, SE, ES, BE, DE and UA license_number_kind: igregulator_reference says the licence number is our key, not the regulator’s.
Plans. Pro and above. Starter keys (a trial account is served as Starter) get 402 payment_required with details.reason: "export_requires_pro" (Pro is paid by card, or by invoice for three months or more — https://app.igregulator.io/billing). 10 exports per UTC day on Pro, 100 on Business, unlimited on Enterprise — API and dashboard counted together; over it → 429 rate_limited, details.reason: "export_daily_limit_reached". An export counts as one request against the monthly quota, whatever its size. A refused request (4xx) counts against neither.
Formats. csv (default): RFC 4180, UTF-8 without BOM, CRLF line ends, a header row, arrays |-joined, objects as JSON text, null as an empty cell; a text starting with = + - @ gets a leading ' so spreadsheets don’t run it as a formula. json: NDJSON — line 1 is {"_meta": ExportMeta}, then one row object per line, keys in column order, values untouched.
Current state only. as_of is not supported (400 as_of_not_supported); for a past status use ?as_of= on /v1/licenses/{license_id}, /v1/operators/{slug} or /v1/check. Rows are read in one statement, so the row count and the rows are the same snapshot; compare the lines you received with X-Export-Row-Count to detect a cut-off download.
Order of checks. The key (401, 402 plan_inactive, the key’s own 429s), then the dataset (404), then the query (400 — any parameter other than format, jurisdiction, status is refused, not ignored), then the plan (402 export_requires_pro), then the daily allowance (429). So a Starter key with a mistyped parameter sees the 400 first.
HEAD. The same checks in the same order and the same status, with no body, without running the export and without using one of the day’s exports: X-Export-Daily-* report the allowance as it stands, and a 200 carries Content-Type, Content-Disposition, Cache-Control and X-Export-Dataset but not X-Export-Row-Count or X-Dataset-Generated-At (nothing was read). Like any answered request it counts as one against the monthly quota.
Row schemas: LicenceExportRow, OperatorExportRow, DomainExportRow. Guide: https://igregulator.io/docs/export/. There is no MCP tool for exports.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”licences (one row per licence), operators (one per legal entity), domains (one per domain ↔ operator link). Case-insensitive; licenses is accepted for licences. Anything else is a 404 (dataset_not_found).
Query Parameters
Section titled “ Query Parameters ”csv or json (NDJSON; ndjson is accepted too). Case-insensitive; anything else is a 400.
Comma-separated jurisdiction codes (case-insensitive; repeat the parameter or use commas). licences: the licence’s jurisdiction. operators: holds a licence there. domains: the jurisdiction of the licence the link’s status comes from. An unknown code is a 400.
Example
UKGC,MGAComma-separated licence statuses (active, suspended, revoked, expired, pending, unknown, surrendered, not_in_register; case-insensitive; repeat the parameter or use commas). licences: the licence’s status. operators: holds a licence with that status — in the jurisdiction given, when both are. domains: the status of the licence the link answers to. An unknown status is a 400.
Example
activeResponses
Section titled “ Responses ”The file, streamed. Content-Disposition: attachment; filename="igregulator-<dataset>-<YYYY-MM-DD>.<csv|ndjson>".
Example
license_id,license_number,license_number_kind,jurisdiction_code,…4db0141c-…,039028-R-319297-014,regulator,UKGC,…One licence per row (GET /v1/export/licences). The same record /v1/licenses/{id} serves, with its status provenance, minus raw_data.
object
IGregulator licence id — what /v1/licenses/{license_id} takes; the record page is https://app.igregulator.io/licenses/<license_id>.
The licence number — for KH, TGC, IOM, ON, SE, ES, BE, DE and UA an iGregulator reference, see license_number_kind.
regulator — the number as the regulator’s register prints it. igregulator_reference — KH (Kahnawake), TGC (Tobique), IOM (Isle of Man), ON (Ontario), SE (Sweden), ES (Spain), BE (Belgium), DE (Germany) and UA (Ukraine) publish no licence number, so the value is a key iGregulator assigned (KH/IG/…, TGC/B2C/…, IOM/OGRA/…, ON/IGO/…, SE/ONLINE/…, SE/BETTING/…, ES/APUESTAS/…, ES/CONCURSOS/…, ES/OTROS-JUEGOS/…, BE/APLUS/…, BE/BPLUS/…, BE/F1PLUS/…, DE/SLOTS/…, DE/POKER/…, DE/SPORTS/…, DE/HORSES/…, UA/CASINO/…, UA/POKER/…, UA/BETTING/…): stable, accepted by /v1/check?license_number=, but no regulator issued it — never quote it as the licence number.
Jurisdiction code: UKGC, MGA, CW (Curaçao), KH (Kahnawake), AN (Anjouan), TGC (Tobique), IOM (Isle of Man), ON (Ontario), SE (Sweden), ES (Spain), BE (Belgium), DE (Germany), CO (Colombia), UA (Ukraine).
The licensee — the key /v1/operators/{slug} takes and the operators export joins on.
The licensee’s name as the register gives it.
Current status. Only active means licensed now; not_in_register, surrendered and unknown are not revocations.
provisional_under_assessment for a Curaçao licence the register reads as “Assessment in progress” past its term (the CGA keeps it in force until it decides); otherwise null. Same value as /v1/check.
The register’s own word for the licence, verbatim — left out (null) where it would contradict the status (an in-force word next to revoked, any word next to not_in_register), the same rule /v1/check applies. Essential when the status is unknown.
The page that published THIS status — often not the register the licence lives in (an enforcement register, a revoked-licences list, an advisory notice). Cite this, not source_url.
When we read this status at status_source_url.
When we last saw the licence listed in its register.
When the register stopped listing it; null while it is listed. On a not_in_register licence this is the “since when” — an observation about the register, not a revocation.
Licence types as the regulator names them (CSV: |-joined).
The type string exactly as the register printed it.
Cross-jurisdiction category: remote, non-remote, ancillary, permit or other.
Issue date, where the register publishes one.
Expiry date, where the register publishes one.
When we last read the register for this licence.
The register the licence is listed in.
Example
{ "license_id": "4db0141c-a863-49b1-808d-75fa49e36fd9", "license_number": "039028-R-319297-014", "license_number_kind": "regulator", "jurisdiction_code": "UKGC", "operator_slug": "hillside-uk-sports-enc", "operator_name": "Hillside (UK Sports) ENC", "status": "active", "status_qualifier": null, "upstream_status": "Active", "status_source_url": "https://www.gamblingcommission.gov.uk/downloads/business-licence-data.zip", "status_observed_at": "2026-09-30T03:10:12.000Z", "last_listed_at": "2026-09-30T03:10:12.000Z", "not_listed_since": null, "license_types": [ "Remote" ], "license_type_raw": "Remote", "license_category": "remote", "issued_date": "2012-10-01", "expiry_date": null, "last_verified_at": "2026-09-30T03:10:12.000Z", "source_url": "https://www.gamblingcommission.gov.uk/downloads/business-licence-data.zip"}One operator (legal entity) per row (GET /v1/export/operators), with where it holds licences. No operator-level status: a multi-jurisdiction operator is never collapsed into one — the licences export has each licence.
object
IGregulator operator id.
The key /v1/operators/{slug} takes and the licences / domains exports carry.
Display name, as the register gives it.
The name the register gives next to the entity — for UKGC often a trading name.
ISO 3166-1 alpha-2, where known.
The operator’s id in each register, keyed by jurisdiction (CSV: JSON text). For KH, TGC, IOM, SE, BE and DE, which publish no identifier, the value is a key we made from the name; for ON it is iGaming Ontario’s directory id; for ES, the DGOJ’s profile slug; for CO, Coljuegos’ contract number; for UA, the company’s EDRPOU code.
object
Jurisdictions where we hold a licence record for it, any status (CSV: |-joined).
Jurisdictions where it holds an active licence — the only “licensed now” (CSV: |-joined).
Licence records, any status.
Licence records whose status is active.
When we last read a register about it; null when we hold no licence for it.
Domain links to this operator, any link status.
Domain links whose own status is active (the regulator lists the domain on this operator). Says nothing about the licence’s status.
When we first recorded the operator.
When its own record (name, ids) last changed.
Example
{ "operator_id": "9d6f21e0-7f34-4b3a-b0a8-ec6c3cab3e11", "operator_slug": "power-leisure-bookmakers-limited", "operator_name": "Power Leisure Bookmakers Limited", "registered_name": "paddy power", "country": "GB", "upstream_ids": { "UKGC": "1034" }, "jurisdictions": [ "UKGC" ], "active_jurisdictions": [ "UKGC" ], "licences_total": 1, "licences_active": 1, "licences_last_verified_at": "2026-09-30T03:10:12.000Z", "domains_total": 12, "domains_active": 11, "created_at": "2026-04-17T15:15:41.414Z", "updated_at": "2026-04-19T03:01:12.200Z"}One domain ↔ operator LINK per row (GET /v1/export/domains): a domain licensed by two entities is two rows, each with its own domain_status. The licence columns are the link’s licence — the one /v1/check reports: the operator’s best licence that can cover a website (UKGC remote or ancillary remote, MGA B2C, the Curaçao licence the row’s certificate names), null when it holds none.
object
The domain as the register lists it.
The operator this link is to.
The operator’s name.
This domain’s status UNDER THIS operator — the link’s own status, not the licence’s. delisted = the regulator removed the domain from this licensee (a positive signal we read, never an absence). The same domain can be active on one row and delisted on another.
direct — the licensee runs the site; white_label — a third-party brand trades under its licence.
The regulator’s own page that names this domain, where we hold one: a Curaçao certificate, a Tobique seal or an MGA verification page. See verification_page_kind for which.
What verification_url is. domain_certificate — a page the regulator issues for this domain alone (a CGA Certificate of Operation, a Tobique validation seal). licence_certificate — the CGA certificate for the licence (cert.cga.cw/token), listing this domain among its “Approved domains”. licensee_page — the MGA verification page for the licensee, listing this domain among its websites. other — a regulator page we have not classified. Null when there is no verification_url.
licensed = link active AND licence active (licensed now); licensed_provisional = the same, for a licence with status_qualifier: provisional_under_assessment (a Curaçao licence the register reads “Assessment in progress” — in force until the CGA decides; also licensed now, with a decision outstanding); licence_not_active = link active, licence anything else — or no licence at all, because the operator holds none that can cover a website (license_id null, jurisdiction_code the regulator that lists the link); delisted = link de-listed by the regulator; other = parked/expired/redirecting, or an operator we hold no licence for. Derived from domain_status, license_status and the register’s wording on this row, nothing else — the same rule as /v1/check’s verdict.
When we first saw this link.
When a source last confirmed this link.
The licence this row’s status comes from — the same pick /v1/check makes: the operator’s best licence that can cover a website (UKGC remote or ancillary remote, never non-remote; MGA B2C only; for Curaçao, the licence the row’s certificate names), active first, then the most recently verified. Null when the operator holds no such licence.
Jurisdiction code: UKGC, MGA, CW (Curaçao), KH (Kahnawake), AN (Anjouan), TGC (Tobique), IOM (Isle of Man), ON (Ontario), SE (Sweden), ES (Spain), BE (Belgium), DE (Germany), CO (Colombia), UA (Ukraine). The regulator that lists the link: the licence’s jurisdiction — or, when license_id is null because the operator holds no licence that can cover a website, the jurisdiction of the licences it does hold. Null only for an operator we hold no licence for.
See license_number_kind.
regulator — the number as the regulator’s register prints it. igregulator_reference — KH (Kahnawake), TGC (Tobique), IOM (Isle of Man), ON (Ontario), SE (Sweden), ES (Spain), BE (Belgium), DE (Germany) and UA (Ukraine) publish no licence number, so the value is a key iGregulator assigned (KH/IG/…, TGC/B2C/…, IOM/OGRA/…, ON/IGO/…, SE/ONLINE/…, SE/BETTING/…, ES/APUESTAS/…, ES/CONCURSOS/…, ES/OTROS-JUEGOS/…, BE/APLUS/…, BE/BPLUS/…, BE/F1PLUS/…, DE/SLOTS/…, DE/POKER/…, DE/SPORTS/…, DE/HORSES/…, UA/CASINO/…, UA/POKER/…, UA/BETTING/…): stable, accepted by /v1/check?license_number=, but no regulator issued it — never quote it as the licence number.
Canonical licence status. Only active means “licensed right now”. Every other value is “not a pass” — but three of them are not enforcement decisions, and a rule that lumps them in with revoked publishes a claim about a real business that no regulator made.
not_in_register — the regulator’s public register no longer lists this licence, since not_listed_since. An observation about the register, not a decision by the regulator: licences drop off because they expired, were surrendered, were renumbered, or the page had a bad day. Nobody published a reason and we do not invent one. It is not a revocation. (Until 2026-09-17 we reported this as revoked; that was wrong, every affected record has been corrected, and its history says so.)
surrendered — the operator gave the licence up (UKGC publishes “Surrendered”; Kahnawake “voluntary termination … in good standing”; the Isle of Man GSC, on its Former Licence Holders list, “Surrendered”). Also not an enforcement decision: nobody took it away. 627 UKGC licences carried revoked for this until 2026-09-17.
unknown — the register lists this licence and published a status we could not classify: a new phrase, a reworded sentence, a typo. We do not guess: two of our scrapers used to default an unreadable status to active, and that is precisely the bug this value exists to make impossible. Read upstream_status for the regulator’s own words. For UA it is also what we store when the last thing PlayCity’s register prints is a court’s ruling on its decision — contested, so neither “licensed” nor “revoked”; there upstream_status is an English rendering of the register’s line. (A UA licence the register says PlayCity terminated by its decision, with no grounds printed, is revoked, its upstream_status keeping that wording.)
None of these is a synonym for any other:
- None of them means “not licensed” in the enforcement sense. Do not present them as such.
- None of them means “probably fine”. Do not treat them as a pass.
A rule like if (status === "revoked") block() will silently let surrendered, not_in_register and unknown through. If your flow makes an automated allow/deny decision, approve only on active and escalate everything else to a human.
revoked and suspended are only ever set from a regulator publication we actually read — an enforcement register, a revoked-licences page, an explicit status column — never from a licence disappearing. (The Isle of Man’s Former Licence Holders list says Cancelled for a licence the Commission cancelled under s.13 of the Online Gambling Regulation Act 2001; we store that as revoked. Ukraine’s PlayCity prints each licence’s revocation, with its decision, on the licence’s own row in its register; we store that as revoked, and a term it says has run out as expired.)
Six registers publish nothing a revocation, suspension or exit can be read from, so neither value is ever set there: ON (iGaming Ontario’s operator directory lists current operators and nothing else — a licence is active or not_in_register), SE (Spelinspektionen’s register lists valid licences only — active, not_in_register, or unknown for a status word other than Aktiv), ES (the DGOJ states licence ends in prose resolutions and fines in a sanctions register, neither read as a status — active or not_in_register), BE (the Gaming Commission publishes lists of active licences and no list of warnings, suspensions or withdrawals — active or not_in_register; a licence still listed past its expiration date stays active), DE (the GGL’s whitelist lists permitted operators only, and its public warnings are not licence statuses — active or not_in_register) and CO (Coljuegos’ page lists its authorised online operators and publishes no structured list of ended concessions — active or not_in_register). Absence from any of them is not_in_register, never a revocation.
provisional_under_assessment for a Curaçao licence the register reads as “Assessment in progress” past its term (the CGA keeps it in force until it decides); otherwise null. Same value as /v1/check.
The register’s own word for the licence, verbatim — left out (null) where it would contradict the status (an in-force word next to revoked, any word next to not_in_register), the same rule /v1/check applies. Essential when the status is unknown.
The page that published THIS status — often not the register the licence lives in (an enforcement register, a revoked-licences list, an advisory notice). Cite this, not source_url.
When we read the licence status at status_source_url.
When we last read the licence’s register.
When the domain was registered, as its registry’s RDAP record states it (the registered name: stake.com for www.stake.com). A fact about the domain, not the licence. Null when we have no record: the TLD publishes no RDAP (e.g. .de, .es, .se, .be), or it is not read yet.
When the domain’s current registration period ends, from the same record.
The sponsoring registrar, as the registry names it.
Example
{ "domain": "spinoloco.com", "operator_slug": "medial-n-v", "operator_name": "Medial N.V.", "domain_status": "active", "domain_association": "direct", "verification_url": "https://cert.cga.cw/token?id=932", "verification_page_kind": "licence_certificate", "standing": "licensed", "link_first_seen": "2026-06-02T01:12:00.000Z", "link_last_verified": "2026-09-29T02:40:00.000Z", "license_id": "1f4b7c0a-2a8e-4c4f-9a2f-6c0d9a7e1b21", "jurisdiction_code": "CW", "license_number": "OGL/2024/1234/0567", "license_number_kind": "regulator", "license_status": "active", "status_qualifier": null, "upstream_status": "Active", "status_source_url": "https://gamingcontrol.spin-cdn.com/media/license_registry/20260921_20260921_ogl_license_registry.pdf", "status_observed_at": "2026-09-29T02:40:00.000Z", "license_last_verified_at": "2026-09-29T02:40:00.000Z", "domain_registered_at": null, "domain_expires_at": null, "domain_registrar": null}object
Line 1 of an NDJSON export: {"_meta": ExportMeta}. No row has a _meta key. (A CSV export has no metadata line; the same facts are in the X-Dataset-Generated-At / X-Export-Row-Count headers and the filename.)
object
When the rows were read.
Rows that follow. Fewer lines than this = a truncated download.
jurisdiction and status as applied (null = not filtered).
object
The codes filtered on, upper-cased.
The statuses filtered on, lower-cased.
Always null: exports are the current state.
Headers
Section titled “ Headers ”Always no-store.
When the rows were read (ISO-8601 UTC).
Rows in the file (the CSV header / NDJSON _meta line not counted).
The dataset served: licences, operators or domains.
Exports per UTC day on your plan (API + dashboard together), or unlimited.
Exports made today, this one included. Omitted when unlimited.
Exports left today. Omitted when unlimited.
Next 00:00 UTC, when the daily counter starts again.
Your plan’s monthly request quota (not the per-second limit). Not sent on a plan with no monthly quota (Business, Enterprise).
What is left of the monthly quota, this request counted. Not sent on a plan with no monthly quota.
Unix epoch seconds of the start of the next UTC month. Not sent on a plan with no monthly quota.
tier=unlimited on a plan with no monthly quota; otherwise not sent.
Always https://igregulator.io/pricing.
The monthly request quota of your plan, or unlimited.
Requests counted this UTC month, this one included (a request that ends in 4xx / 5xx is not counted). Not sent when the limit is unlimited.
What is left of the monthly quota. Not sent when unlimited.
When the monthly counter starts again: the first of next month, 00:00 UTC, ISO-8601. Not sent when unlimited.
80% of monthly limit used — sent from 80% of the quota on, absent before.
as_of was sent (as_of_not_supported); a parameter other than format, jurisdiction, status; a format that is not csv / json; an unknown status or jurisdiction code.
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Examples
{ "error": "as_of is not supported on exports", "code": "invalid_query", "details": { "reason": "as_of_not_supported", "field": "as_of", "suggestion": "An export is the current state only. For a status on a past date, pass ?as_of= to /v1/licenses/{id}, /v1/operators/{slug} or /v1/check." }}{ "error": "format must be csv or json", "code": "invalid_query", "details": { "reason": "invalid_input", "field": "format", "suggestion": "?format=csv (default) or ?format=json — json is NDJSON, one object per line." }}The API key is missing, malformed, unknown or revoked. On an endpoint that works without a key this is only ever sent when a key WAS sent and is not valid — drop the header, or fix the key.
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Examples
{ "error": "Authorization header required", "code": "auth_required", "details": { "reason": "api_key_missing", "suggestion": "Attach an API key: `Authorization: Bearer <key>`. No key yet? Start a 14-day free trial of Starter (card required) at https://app.igregulator.io/signup; an existing account creates keys at https://app.igregulator.io/api-keys." }}{ "error": "Authorization header must be \"Bearer <key>\"", "code": "auth_invalid", "details": { "reason": "malformed_header", "suggestion": "Header format: `Authorization: Bearer <your-api-key>`." }}{ "error": "API key not recognized", "code": "auth_invalid", "details": { "reason": "api_key_invalid", "suggestion": "Double-check the key. Create a new one at https://app.igregulator.io/api-keys if the previous one was deleted." }}{ "error": "API key has been revoked", "code": "auth_revoked", "details": { "reason": "api_key_revoked", "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored." }}Export is a Pro feature: Starter keys see the endpoint and get this, never a row. (A canceled or plan-less account gets plan_inactive instead.)
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Example
{ "error": "CSV/JSON export is a Pro feature", "code": "payment_required", "details": { "reason": "export_requires_pro", "plan_tier": "starter", "required_plan": "pro", "suggestion": "CSV/JSON export is part of Pro. Pro is paid by card, or by invoice for three months or more — https://app.igregulator.io/billing." }}Headers
Section titled “ Headers ”dataset is not licences, operators or domains.
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Example
{ "error": "Unknown export dataset", "code": "not_found", "details": { "reason": "dataset_not_found", "field": "dataset", "suggestion": "Datasets: licences, operators, domains — e.g. GET /v1/export/licences?format=csv. See https://igregulator.io/docs/export/." }}Today’s exports are used up (export_daily_limit_reached, with Retry-After = seconds to 00:00 UTC) — or one of the key’s own limits, as on every keyed endpoint (monthly_request_limit_reached, per_second_limit_exceeded; those do not carry the X-Export-* headers).
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Example
{ "error": "Daily export limit reached", "code": "rate_limited", "details": { "reason": "export_daily_limit_reached", "current_usage": 10, "limit": 10, "reset_at": "2026-10-01T00:00:00.000Z", "plan_tier": "pro", "suggestion": "Your plan includes 10 exports per UTC day, API and dashboard together; the counter resets at reset_at (00:00 UTC). Need more? Email founder@igregulator.io." }}Headers
Section titled “ Headers ”Exports per UTC day on your plan (API + dashboard together), or unlimited.
Exports made today, this one included. Omitted when unlimited.
Exports left today. Omitted when unlimited.
Next 00:00 UTC, when the daily counter starts again.
Unexpected server error. Safe to retry.
The body of every non-2xx response.
object
Human-readable summary. The wording can change; do not branch on it.
The error class. Mostly one per HTTP status, with two exceptions to know: quota_exceeded is a 429 for the monthly request quota and a 403 for a plan cap (watchlist size, webhook endpoints). A 409 carries conflict (it carried invalid_query before 1.24.0). Branch on the HTTP status and details.reason. forbidden is only ever sent to a signed-in MCP connection, never to an API key.
Always present. reason is always set; field and suggestion when they apply; limit errors add the numbers below.
object
Machine-readable refinement of the top-level code — branch on this. Values: invalid_input, missing_required_parameter, conflicting_parameters, not_a_valid_hostname, hostname_too_long, invalid_pagination, invalid_cursor, since_exceeds_retention_window, invalid_event_type, invalid_jurisdiction, as_of_not_supported, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, plan_inactive, plan_ended, export_requires_pro, geo_checks_require_business, watchlist_quota_exceeded, webhook_quota_exceeded, operator_not_found, license_not_found, jurisdiction_not_found, webhook_not_found, dataset_not_found, route_not_found, method_not_allowed, watchlist_duplicate, no_active_secret, quota_exceeded, monthly_request_limit_reached, per_second_limit_exceeded, watchlist_events_poll_limit, export_daily_limit_reached, geo_check_quota_exceeded, internal_error. A rejected webhook URL carries the SSRF check’s reason (invalid_url, invalid_scheme, empty_host, blocked_hostname, unresolvable_host, private_ip_blocked). New values can be added.
Present only when the error maps to a specific request input (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).
A hint a person or an agent can act on. Present on every error today.
On a limit error (429, and the 403 plan caps): the ceiling that was reached.
On a keyed limit error: how much of limit is used. Not on the keyless per-IP 429 or the watchlist-poll 429.
When the counter starts again — on the keyless per-IP 429, the monthly quota, the watchlist-poll limit and the export daily limit. Not on the per-second limit (retry after one second).
The key’s plan, on plan-scoped limit errors and on export_requires_pro.
On export_requires_pro: the lowest plan that includes the feature.
On watchlist_events_poll_limit: always hour.
Example
{ "error": "Internal server error", "code": "server_error", "details": { "reason": "internal_error", "suggestion": "Retry with exponential backoff (1s / 2s / 4s). If the error persists past 4 seconds, surface failure state to the user instead of looping." }}