> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get coverage gaps > Returns the ledger ranges whose matching events were not delivered to this endpoint, with the reason for each gap (for example paused_by_user or free_quota_exhausted), and the ledger before which you read history from the Activity API instead. ## OpenAPI ````yaml /api-reference/webhooks.json get /v1/subscriptions/{id}/coverage openapi: 3.0.3 info: title: Lumeus Webhooks API version: '2026-09-15' description: >- Lumeus Webhooks API on Stellar. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet webhook deliveries cost no credits. A Free organization gets one Testnet endpoint with up to 1,000 deliveries a day. On paid plans each delivered Mainnet event costs 1 credit from the monthly balance. Calls to this management API are not charged. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer whk_…`, a webhook key from the dashboard. Webhook keys belong to one network, so pick the server that matches the key. `lum_` API keys are not accepted here (401). - **Headers.** Every response carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON with a machine-readable code (see [errors](/guides/errors)). A path with an empty, `.` or `..` segment answers 400 invalid_request, a trailing slash answers 404 not_found, and a method the path does not accept answers 405 with an Allow header. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://webhooks-testnet.lumeus.dev description: Testnet (default) - url: https://webhooks.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: Webhook keys description: >- Create, list and revoke the `whk_` keys that manage webhook endpoints on one network. - name: Subscriptions description: >- Create, list, read, change, pause and delete webhook endpoints (subscriptions) and their event filters. - name: Deliveries description: >- What was delivered to an endpoint: recent deliveries, coverage gaps and signed test events. - name: Signing keys description: >- Rotate an endpoint's whsec_ signing secret with a 24-hour overlap, or end the overlap early. - name: Replay description: >- Redeliver past events or replay a ledger range to an endpoint, priced by a quote first. Free and paid plan endpoints get 403 today. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /v1/subscriptions/{id}/coverage: get: tags: - Deliveries summary: Get coverage gaps description: >- Returns the ledger ranges whose matching events were not delivered to this endpoint, with the reason for each gap (for example paused_by_user or free_quota_exhausted), and the ledger before which you read history from the Activity API instead. operationId: getCoverageGaps parameters: - name: id in: path required: true description: >- Endpoint (subscription) ID from `POST /v1/subscriptions` or `GET /v1/subscriptions`. The example ID is a placeholder and answers 404: use your own. schema: type: string format: uuid example: 00000000-0000-4000-8000-000000000000 x-default: 00000000-0000-4000-8000-000000000000 example: 00000000-0000-4000-8000-000000000000 responses: '200': description: The endpoint and its coverage gaps. content: application/json: schema: $ref: '#/components/schemas/Coverage' example: gaps: - first_ledger: 5293268 last_ledger: 5293268 reason: free_quota_exhausted approximate: false - first_ledger: 5293270 last_ledger: 5293270 reason: free_quota_exhausted approximate: false historical_until_ledger: 5293205 subscription: id: 00000000-0000-4000-8000-000000000000 name: my-app target_url: https://example.com/webhooks asset: native event_types: - transfer active: false created_at: '2026-10-20T09:46:50.582763Z' admission_protocol: 2 version: 2 desired_state: deleted effective_state: deleted slot_state: sponsored sponsored: true signing_version: 1 generation: testnet-2025-12-18-v2 activation_checkpoint: 5293204 effective_checkpoint: 5293284 last_scanned_ledger: 5293284 last_fully_admitted_ledger: 5293271 metered: false headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '400': $ref: '#/components/responses/HTTP400_5' '401': $ref: '#/components/responses/HTTP401' '403': $ref: '#/components/responses/HTTP403' '404': $ref: '#/components/responses/HTTP404_2' '405': $ref: '#/components/responses/HTTP405_5' '429': $ref: '#/components/responses/HTTP429' '503': $ref: '#/components/responses/HTTP503_3' x-codeSamples: - lang: bash label: cURL source: >- # Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. curl --fail-with-body -sS 'https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/coverage' \ -H "Authorization: Bearer $LUMEUS_WEBHOOK_KEY" - lang: javascript label: JavaScript source: >- // Node 18+ (ES module) // Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. const res = await fetch('https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/coverage', { method: 'GET', headers: { Authorization: `Bearer ${process.env.LUMEUS_WEBHOOK_KEY}`, }, }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: >- # Use a subscription id from POST or GET /v1/subscriptions; the placeholder answers 404. import json import os import requests res = requests.get( "https://webhooks-testnet.lumeus.dev/v1/subscriptions/00000000-0000-4000-8000-000000000000/coverage", headers={"Authorization": f"Bearer {os.environ['LUMEUS_WEBHOOK_KEY']}"}, timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: schemas: Coverage: type: object properties: subscription: $ref: '#/components/schemas/Subscription' gaps: type: array items: type: object properties: first_ledger: type: integer last_ledger: type: integer reason: type: string description: >- For example paused_by_user, awaiting_activation, funding_exhausted, payload_or_policy_limit (more than 4,096 matches in one ledger, or an oversized event), free_quota_exhausted (free Testnet daily cap), free_webhooks_disabled, plan_not_entitled (paid endpoint while the organization is not on a paid plan), paid_webhooks_disabled or multiple_causes. approximate: type: boolean historical_until_ledger: type: integer description: >- Exclusive Activity boundary: activation checkpoint + 1. Null before activation. nullable: true required: - subscription - gaps - historical_until_ledger Subscription: type: object properties: id: type: string format: uuid name: type: string description: Endpoint label. target_url: type: string description: HTTPS URL that receives the signed POSTs. hmac_secret: type: string description: >- Returned only by the first successful creation; retries do not reveal it. account: type: string description: Account filter, when set. asset: type: string description: Asset filter, when set. contract_addr: type: string description: Contract filter, when set. event_types: type: array items: type: string description: Event type filter; absent or empty means every decoded event type. active: type: boolean description: True while the endpoint receives events. created_at: type: string format: date-time admission_protocol: type: integer description: 'Delivery protocol version (2: deliveries carry a signed context).' version: type: integer description: >- Endpoint version, also in the ETag header. Every change increments it. desired_state: type: string description: 'What you asked for: active, paused or deleted.' effective_state: type: string description: >- What applies now: active, activating, paused_by_user, paused_by_funding (for example the free daily cap was reached) or deleted. slot_state: type: string description: >- metered for paid-plan endpoints, sponsored for the free Testnet endpoint, held for prepaid funded endpoints. sponsored: type: boolean description: >- True for the one free Testnet endpoint of a Free organization: deliveries are not charged credits but are capped per UTC day, and replays are not available. metered: type: boolean description: >- True for a paid-plan endpoint: every delivered Mainnet event costs the catalog webhook credit weight (1 credit) from the organization's monthly balance, with overage billed on paid plans. Testnet deliveries, and failed, cancelled and expired deliveries, cost nothing. Replays are not yet available for paid endpoints. signing_version: type: integer description: Version of the current signing secret; rotation increments it. generation: type: string description: Event index generation the endpoint reads. activation_checkpoint: type: integer description: >- The endpoint receives events from the ledger after this one. Read earlier history from the Activity API. effective_checkpoint: type: integer description: Last ledger the endpoint's state applies to. last_scanned_ledger: type: integer description: Last ledger scanned for matching events. last_fully_admitted_ledger: type: integer description: Last ledger whose matching events were all queued for delivery. free_quota: type: object properties: day: type: string description: UTC date (YYYY-MM-DD). daily_cap: type: integer admitted: type: integer description: >- Admitted today; deliveries cancelled before any attempt are given back. delivered: type: integer required: - day - daily_cap - admitted - delivered description: >- Free Testnet endpoints only, on `GET /v1/subscriptions/{id}`: the organization's admitted and delivered deliveries today (UTC) against its daily cap. paid: type: object properties: plan: type: string endpoint_limit: type: integer description: Paid endpoints allowed per network on this plan. endpoints_used: type: integer description: Active paid endpoints of the organization on this network. credits_per_delivery: type: integer required: - plan - endpoint_limit - endpoints_used - credits_per_delivery description: Paid endpoints only, on `GET /v1/subscriptions/{id}`. warnings: type: array items: type: string description: >- Create and update responses only: non-fatal filter warnings, such as a probable event type typo. required: - id - target_url - active - created_at - admission_protocol - version - desired_state - effective_state - slot_state - sponsored - metered - signing_version Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error responses: HTTP400_5: description: >- Invalid input (code invalid_request). The message names the problem. Fix the request; do not retry it unchanged. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: subscription id must be a UUID request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP401: description: >- Missing, invalid, revoked or expired key, or a key for the other network (code unauthorized). Keys work only on the network they were created for. content: application/json: schema: $ref: '#/components/schemas/Error' examples: No key: summary: No key value: code: unauthorized error: missing credentials request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Invalid key: summary: Unknown, revoked or expired whk_ key value: code: unauthorized error: invalid or revoked API key request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP403: description: >- This key or account cannot call this route (code forbidden): for example a read-only key on a workspace route, or a publishable key on a route or from an origin it does not allow. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden error: confirm your email address to manage webhooks request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP404_2: description: Not found in this organization and network (code not_found). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found error: subscription not found request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP405_5: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: >- method POST is not allowed on /v1/subscriptions/00000000-0000-4000-8000-000000000000/coverage; allowed: GET, HEAD request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP429: description: >- The Webhooks management rate limit was reached (code rate_limited). Wait Retry-After seconds. The daily Testnet request cap of Activity, Assets and RPC does not apply to the Webhooks API. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited error: webhook management rate limit exceeded request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer HTTP503_3: description: >- Temporarily unavailable (code unavailable), for example the management limiter or the database. Wait Retry-After seconds and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unavailable error: webhook control is temporarily unavailable request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ Retry-After: description: Seconds to wait before retrying. schema: type: integer securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer whk_…`, a webhook key from the dashboard. Webhook keys belong to one network, so pick the server that matches the key. `lum_` API keys are not accepted here (401). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.