Skip to content
iGregulator docs

Polling fallback feed for watchlist events

GET
/v1/watchlist/events

Cursor-paginated list of webhook-shape events (same envelope and event_id, minus the per-delivery signature). Use as a fallback when an inbound webhook receiver is not feasible — corporate networks, agents without a public URL, backfill after webhook outages.

Which events — every operator event (license.*, regulatory_action.added) about an operator currently on the caller’s watchlist, whether or not the caller has a webhook endpoint; plus any event that was queued for one of the caller’s endpoints (e.g. coverage.* for an endpoint subscribed to it). An event whose underlying licence-history row we have since withdrawn as wrong is not served.

Pass since=<ISO> for the first call (bootstrap window, max 30 days). Subsequent calls pass the next_cursor from the previous response. Don’t pass both.

Rate limit — separate from the monthly quota. Per-hour ceiling per plan: Starter 10, Pro 60, Business 600, Enterprise unlimited. 429 with details.reason=watchlist_events_poll_limit when exhausted.

Every response carries X-Poll-RateLimit-{Limit,Remaining,Reset,Window} plus X-Poll-Recommended-Interval (seconds the SDK should sleep between polls to stay under the ceiling).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
since
string format: date-time

ISO-8601 timestamp. Returns events created after this point. Window capped at 30 days (matches webhook_events retention).

cursor
string
<= 512 characters

Opaque base64url cursor returned from the previous response.

limit
integer
default: 100 >= 1 <= 500

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Events page.

object
events
required
Array<object>

Common shape across every webhook event (and every entry in /v1/watchlist/events). The data block varies by event — see https://igregulator.io/docs/webhooks/ for per-event field tables.

object
event
required
string
Allowed values: license.status_changed license.expiring_30d license.expiring_60d license.expiring_90d license.expired license.issued regulatory_action.added coverage.degraded coverage.restored webhook.endpoint_degraded
event_id
required
string
evt_01HX8EGQK3J7WA6MYTP7ZGYF21
api_version
required
string
2026-04-20
timestamp
required
string format: date-time
livemode
required
boolean
data
required
object
key
additional properties
any
{
  "event": "license.status_changed",
  "event_id": "evt_01HX8EGQK3J7WA6MYTP7ZGYF21",
  "api_version": "2026-04-20",
  "timestamp": "2026-04-20T14:32:00.000Z",
  "livemode": true,
  "data": {
    "license_id": "4db0141c-a863-49b1-808d-75fa49e36fd9",
    "license_number": "039028-R-319297-014",
    "operator_id": "00000000-0000-0000-0000-000000000000",
    "operator_slug": "888-uk-limited",
    "jurisdiction_code": "UKGC",
    "previous_status": "active",
    "new_status": "suspended",
    "changed_at": "2026-04-20T03:04:12.000Z",
    "source_url": "https://www.gamblingcommission.gov.uk/..."
  }
}
next_cursor
string | null
has_more
required
boolean

Headers

Section titled “Headers ”
X-Poll-RateLimit-Limit
string

Per-hour poll ceiling for the caller’s plan, or unlimited.

X-Poll-RateLimit-Remaining
integer

Polls remaining this hour. Omitted when the limit is unlimited.

X-Poll-RateLimit-Reset
string format: date-time

ISO-8601 timestamp when the per-hour counter rolls over.

X-Poll-RateLimit-Window
string

Always hour.

X-Poll-Recommended-Interval
integer

Recommended seconds between polls — ceil(3600 / limit). SDKs that sleep this long never hit the limit by construction.

400

Section titled “400 ”

Invalid query / parameters.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, export_requires_pro, export_daily_limit_reached, as_of_not_supported, dataset_not_found, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored."
}
{
  "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."
  }
}

401

Section titled “401 ”

Missing / malformed / revoked API key.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, export_requires_pro, export_daily_limit_reached, as_of_not_supported, dataset_not_found, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored."
}
{
  "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."
  }
}

402

Section titled “402 ”

The key’s plan does not cover this request — canceled or no plan (plan_inactive), or a legacy trial key calling anything but /v1/check and the other endpoints that work without a key (endpoint_requires_paid_plan), or a plan below Pro asking for an export (export_requires_pro). Paid plans are not on sale yet: email founder@igregulator.io and we will sort it out.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, export_requires_pro, export_daily_limit_reached, as_of_not_supported, dataset_not_found, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored."
}
{
  "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."
  }
}

429

Section titled “429 ”

Rate limit reached. Public endpoints: 10 req / IP / hour — a free API key (no card, 10,000 requests / month) from https://app.igregulator.io/signup lifts it. Authenticated: per plan tier; paid tiers are not open yet, so email founder@igregulator.io for a higher limit. Retry after the window surfaced in X-RateLimit-Reset.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, export_requires_pro, export_daily_limit_reached, as_of_not_supported, dataset_not_found, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored."
}
{
  "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."
  }
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
X-RateLimit-Reset
integer

Unix epoch seconds.

X-Upgrade-URL
string format: uri

500

Section titled “500 ”

Unexpected server error.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, export_requires_pro, export_daily_limit_reached, as_of_not_supported, dataset_not_found, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/api-keys. Revoked keys cannot be restored."
}
{
  "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."
  }
}