Social Fetch
Start for freeStart free
Polymarket hub

Polymarket Event Annotations API

Dated explanations of an event's price moves, with the outcome, the change and the sources cited.

GET /v1/polymarket/events/{eventIdOrSlug}/annotations

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/polymarket/events/{eventIdOrSlug}/annotations returns data.annotations, newest first. Each annotation has at (when the price moved), title, summary, outcome, priceBefore, priceAfter, priceChange and sources[] with each publisher's name and article url. data.eventId and data.slug identify the event.

Pass outcome to keep only annotations about one outcome, matched on its name without regard to case. Only events with large price moves carry annotations, so an empty array is a normal found answer.

Polymarket Event Annotations API FAQ

Why is the annotations array empty?

Annotations are written for events that had a large price move. A quiet event, or one that was recently created, usually has none. An empty array on lookupStatus: found is correct, not a failure.

How do I filter to one outcome?

Pass outcome with the outcome's name, for example Yes or a candidate name. The match ignores case. Omit it to get every annotation for the event.

Do annotations cover every price change?

No. They are selected explanations, not a complete tick history. For a complete series use GET /v1/polymarket/tokens/{tokenId}/price-history, and for individual fills use the trades routes.

What does lookupStatus mean on this route?

found means the object or list was returned. not_found means no matching object exists. HTTP 200 only means the request finished, so branch on data.lookupStatus before storing a row.

How much does this route cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

Other Polymarket endpoints