TextKitDocs

Long-poll for new events

Holds the request until an event newer than cursor exists or timeout seconds pass, then returns the new events oldest first and the cursor to send next.

GET/v1/events/wait

Query Parameters

Results are paged. When has_more is true, pass next_cursor from the response as cursor to fetch the next page.

  • cursorstring

    The cursor of the previous response. Omit on the first call.

  • timeoutinteger

    Seconds to hold the request. Default 20. Maximum 25. Minimum 0.

Details

Call once without cursor to get one that means "from now" (answers immediately, empty). An event can be returned more than once: de-duplicate by id.

Reads the event log only: no webhook endpoint is called and no delivery is recorded. This is what textkit listen runs on.

Rate limit: 600 requests per 5 minutes, separate from other calls. Scope: webhooks.

Responses

  • 200Page of Event

    New events, oldest first

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429Error

    Rate limit or quota exceeded

Response Fields

The body is a page: data (the array), has_more, and next_cursor (null on the last page). Each item in data:

  • idstring

    Example: evt_a1B2c3D4e5F6g7H8.

  • objectevent
  • typemessage.sent, message.delivered, message.failed, message.received, message.opted_out, message.opted_in, message.help_requested, message.blocked, message.deferred, message.link_clicked, broadcast.complete, number.purchased, number.released, number.sender_updated, verification.sent, verification.approved, verification.failed, verification.blocked, verification.sent_to_opted_out, registration.updated, deliverability.degraded, compliance.flagged, compliance.paused, compliance.resumed, spend.threshold_reached, credits.low, credits.depleted, credits.topped_up, credits.auto_recharge_failed, automation.run.started, automation.run.completed, automation.run.failed, schedule.occurrence_skipped, schedule.paused, batch.created, batch.paused, batch.resumed, batch.canceled, batch.retried, batch.complete
  • modetest, live

    Sandbox or live traffic. A key sees only its own mode's events, and an endpoint receives only its own mode's.

  • created_atstring (date-time)
  • dataobject

    The subject of the event. Events about one message (message.sent, .delivered, .failed, .received, .blocked) include message_id, its price (the same object GET /v1/messages/{id} shows) and its tags when it has any.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 429

    Rate limit or quota exceeded