# Long-Poll Drain: Fetch Unacked Inbox Events

> Long-Poll Drain: Fetch Unacked Inbox Events is a free API for AI agents from inbox.withzero.xyz, callable via MPP, free · handshake required, status unknown (last checked 2026-09-15, last successful call 2026-07-29).

Returns unacked events from the agent's inbox using long-polling, optionally filtered by topic glob pattern.

## Facts

- Endpoint: GET https://inbox.withzero.xyz/api/v1/inbox
- Price: free · handshake required
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-15
- Last successful call: 2026-07-29
- Success rate: 100% of calls made through Zero
- Activations on Zero: 211
- Provider: inbox.withzero.xyz
- Website: https://inbox.withzero.xyz
- Canonical page: https://www.zero.xyz/c/inbox-withzero-xyz-long-poll-drain-fetch-unacked-inbox-events-f3139f8c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_n4aK-joG27UzNSelaO8ds

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability inbox-withzero-xyz-long-poll-drain-fetch-unacked-inbox-events-f3139f8c
```

Example prompt: Check my inbox.withzero.xyz inbox for any unacked events — wait up to 20 seconds for new ones, and only return messages matching the topic pattern 'render.*'.

## When to prefer this

Use this endpoint when an agent wakes up and needs to consume queued events from its durable inbox. Prefer this over webhook-based approaches when the agent has no persistent process running between invocations. Use the topic filter when only specific event types are relevant to the current task. Use long-poll (wait > 0) to block until an event arrives rather than busy-polling.

## Known failure modes

- No events arrive within the long-poll window — returns empty events array with null cursor
- Invalid topic glob pattern — may return no results or a 400 error
- Expired or missing signed proof credential — returns 401 unauthorized
- Inbox not yet provisioned — returns 404 or lease-not-found error
- wait parameter out of range (must be 0-30) — returns 400 bad request
- Network timeout if wait exceeds client timeout settings

## How this service works

Long-poll drain: return unacked events, optionally filtered by topic. 📖 Full guide: https://inbox.withzero.xyz/llms.txt

## Output

Returns an array of unacked events (each with id, topic, payload, attributes, and publishedAt timestamp) plus a cursor pointing to the last event returned (null if no events). The agent should use the cursor and then call the ack endpoint to mark events as handled.

## Example request

```json
{}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "events",
  "cursor"
 ],
 "properties": {
  "cursor": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "description": "Id of the last event returned; null when empty."
  },
  "events": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "id",
     "topic",
     "payload",
     "attributes",
     "publishedAt"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "topic": {
      "type": "string"
     },
     "payload": {},
     "attributes": {
      "anyOf": [
       {},
       {
        "type": "null"
       }
      ]
     },
     "publishedAt": {
      "type": "string"
     }
    },
    "additionalProperties": false
   }
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/inbox-withzero-xyz-long-poll-drain-fetch-unacked-inbox-events-f3139f8c/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from inbox.withzero.xyz](https://www.zero.xyz/host/inbox.withzero.xyz/llms.txt)