---
title: "Poll bid-outcome events (for clients without webhooks)"
method: GET
path: "/api/v1/offers/events"
tags: ["Outcomes"]
---

# Poll bid-outcome events (for clients without webhooks)

`GET /api/v1/offers/events`

## Request

- Base URL: `https://www.upgradeagent.ai`
- URL: `https://www.upgradeagent.ai/api/v1/offers/events`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://www.upgradeagent.ai/api/oauth/authorize`, token URL `https://www.upgradeagent.ai/api/oauth/token`, scopes: `mcp`)
  - HTTP bearer

The MCP `get_offer_events` tool. The ordered log of bid-outcome events — the same events webhooks deliver — for one quote (`quoteId`) or for every quote this caller owns (omit it). Pass `since` = the previous response's `nextCursor` (or an ISO timestamp) to receive only what's new. A quote whose traveler hasn't completed the check yet returns an empty page, not 409.

## Query parameters

- `quoteId` string
- `since` string
- `limit` integer: 1–200, default 50.

## Response `200`

Events, oldest first, with the cursor for the next poll.

- OfferEventList
  - `quoteId` string, nullable, required: The quote filtered on, or null for all of the caller's quotes.
  - `events` OfferEvent[], required: Oldest → newest.
    - `id` string, required: Event id — also the polling cursor (pass as `since`).
    - `event` 'offer.status_changed' | 'offer.accepted' | 'offer.declined' | 'offer.cancelled' | 'checkout.paid', required: Event name.
    - `occurredAt` string, required: ISO-8601 time of the observation that produced the event.
    - `data` OfferEventPayload, required: Non-PII by construction: never a booking reference, last name, or contact detail.
      - `event` 'offer.status_changed' | 'offer.accepted' | 'offer.declined' | 'offer.cancelled' | 'checkout.paid' | 'ping', required: Event name (or `ping` for test deliveries).
      - `quoteId` string, nullable, required: The quote the offer belongs to.
      - `offerReference` string, nullable, required: Operator order-change id (the offerReference on GET /offers); null for checkout.paid when ambiguous.
      - `status` string, nullable, required: New normalized status: submitted | pending | accepted | declined | cancelled | paid | unknown.
      - `previousStatus` string, nullable, required: Previous normalized status; null on first observation.
      - `amount` number, nullable, required: Offer amount.
      - `currency` string, nullable, required: ISO currency, or PTS for points.
      - `cabin` string, nullable, required: Cabin / product name.
      - `segment` string, nullable, required: Route, e.g. NCE-ZRH.
      - `occurredAt` string, required: ISO-8601 time of the observation.
  - `nextCursor` string, nullable, required: Pass as `since` on the next call; null when no events were returned.
  - `eventTypes` string[], required

## Other responses

- `400`: Bad since/limit.
- `401`: Missing, invalid, expired, or revoked bearer token. The WWW-Authenticate challenge points at the OAuth protected-resource metadata.
- `404`: Unknown quote, or owned by another caller.
- `429`: Per-caller rate limit exceeded.

---

[API](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api.md) · [All operations](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/revisions/fbed715712c1?raw)