Check Listing
check_listingPoll the current status and action feed for the listing tied to this call's correlation id.
IDENTITY: the correlation id is never a tool argument. It must ride the
X-XP-Correlation-Id HTTP header on every MCP request, exactly like on
every other tool call for this job. A missing/invalid header returns a
structured error (below) instead of failing the call -- this tool is
open-world (no bearer/OAuth needed); holding the correlation id (an
unguessable v4 uuid) is itself the access control.
ARGS
since: the cursor value returned by the previous call for this
same correlation id. Omit (or pass null) on the first call to
fetch the full action feed from the beginning. Must be >= 0;
a negative value returns {"error": "invalid_since"}.
POLL LOOP: store cursor per correlation id in your own
cache/store, send it back as since on the next call, and render
only the new actions entries onto your own timeline -- the array
already excludes anything at or before since and is empty when
nothing changed. listing is a snapshot for cheap "current state"
display only (quantity, bid count, bucket, ...); do not diff it
yourself for history -- actions is the exact, ordered record (a
bid placed and rescinded between two polls still yields both events).
RESULT SCHEMA (found: false -> every other field is null/absent;
an unrecognized correlation id is not an error, just an empty result)::
{
"correlation_id": "<uuid>",
"found": true,
"verified": true, # identity confirmed when the listing was created
"event_id": 406, # last event this correlation looked at
"listing": { # null until a listing exists for this id
"swap": "d5b03i1rbqqa", # public listing identifier (sell/checkout URLs)
"created_at": "2026-08-12T14:00:00+00:00",
"status_bucket": "open", # see BUCKETS below
"event_id": 406,
"quantity": 2,
"bid_count": 3,
"top_bid_amount": 12000, # cents, open bids, null if none
"accepted_bid_amount": null, # cents, set once a bid is accepted
"sold": false,
"last_activity_at": "2026-08-12T14:05:00+00:00"
},
"actions": [ # everything after `since`, oldest first, [] if nothing new
{"id": 91234, "event": "listing_created", "at": "2026-08-12T14:00:00+00:00"},
{"id": 91288, "event": "bid_placed", "at": "2026-08-12T14:03:10+00:00", "amount": 12000}
],
"cursor": 91301, # send back as `since` on the next call
"actions_truncated": true # present+true only when 50+ new rows; call again with `cursor` to page
}BUCKETS (listing.status_bucket) open - accepting bids, none accepted yet awaiting_tickets - a bid was accepted; seller hasn't transferred tickets yet buyer_has_tickets - tickets transferred; seller payout not yet finalized seller_payout - funds are ready to release to the seller zombies - stalled, no forward progress -- needs attention closed - terminal: cancelled, expired, or fully settled
EVENT VOCABULARY (actions[].event; only bid/sale events carry amount, in cents)
listing_created, bid_placed, bid_rescinded, bid_accepted, bid_rejected,
tickets_transferred, funds_claimed, listing_cancelled,
listing_expired, sale_completed
NOTE: no separate payout-completion signal exists -- the agent-forward
payout rail is retired; sellers claim funds normally (funds_claimed).
FAILURES: this tool never raises and never returns an auth error (401). {"error": "missing_correlation_header", "message": "..."} - header missing/invalid {"error": "invalid_since"} - since < 0 {"error": "status_unavailable"} - backend down/slow/non-200
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Cursor from the previous call's `cursor` field. Omit/null on the first call to fetch the action feed from the beginning. Must be >= 0. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||