---
title: "pollOutboundMessages"
method: POST
path: "/v1/integrations/{integrationId}/outbound/messages/poll"
tags: ["integrations"]
---

# pollOutboundMessages

`POST /v1/integrations/{integrationId}/outbound/messages/poll`

Poll outbound messages for an integration's poll-mode use cases.
Takes a lease on the head-of-line batch of the integration's FIFO stream:
the returned messages stay invisible to subsequent polls until they are
acknowledged or the visibility timeout elapses. POST because taking a
lease mutates server state — auto-retrying middleware must not burn
leases. One in-flight batch per stream: while a lease is active (or
another poll wins the race), the response is an empty batch
(`messages: []`), not an error. Requires the `integration:consume` grant.

## Path parameters

- `integrationId` string, uuid, required

## Request body

- PollOutboundMessagesRequest
  - `limit` integer — Maximum number of messages to lease in this batch. The ~5.5 MB response cap may truncate the batch earlier when payloads are large — the leased run shrinks accordingly.

## Response `200`

Leased batch of outbound messages (possibly empty)

- PollOutboundMessagesResponse
  - `messages` OutboundMessage[], required — The leased batch in strict stream order (empty when contended or drained)
    - `id` string, required — Opaque message id (msg_…) — stable per message across leases
    - `lease_token` string, required — Opaque lease token (lt_…) — echo back on ack
    - `use_case_id` string, required — The poll-mode use case that produced this message
    - `event_name` string, required — Standardized event name (e.g. contract.updated)
    - `event_id` string, required — Unique id of the originating event
    - `group` string, required — Ordering group — messages sharing a group are strictly ordered, distinct groups are independent. Constant "0" in v1.
    - `payload` object, required — The raw standardized event-catalog event, always inlined as-is
    - `enqueued_at` string, date-time, required — When the message was enqueued
  - `visibility_timeout_seconds` integer, required — Effective visibility timeout for this lease — a per-integration server-side setting (default 300 seconds)
  - `has_more` boolean, required — Whether more messages are available beyond this batch

## Other responses

- `400` — Bad request
- `401` — Unauthorized request
- `403` — Forbidden - insufficient permissions
- `404` — Resource not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/epilot/apis/integration-toolkit-api.md) · [All operations](https://skmtc.net/epilot/apis/integration-toolkit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/integration-toolkit-api/revisions/a567add0c3f5/schema)