Get similar events
Get events similar to a reference event.
The reference event is resolved from the highest-priority non-empty input in this order: id → event_slug → market_slug → event_title → market_title. At least one must be provided.
Only active=true events are ever returned (no caller-facing opt-out). The optional closed query parameter further constrains results to either closed=true (resolved) or closed=false (open) events; when omitted, both are returned.
When no similar events can be resolved, the endpoint falls back to a default set of active+open events. Successful responses advertise Cache-Control: public, max-age=300 for similar events or public, max-age=30 for the popular fallback, including an empty fallback.
Markets are not loaded unless include_markets=true. With markets_limit=N (1–10) each event keeps only its N most likely markets: open markets (active, not closed or archived) first, then by first outcome price descending. This is the shape a "you might also like" rail needs without a second read per event.
Request
- Base URL: https://gamma-api.polymarket.com (the document declares no server; this is the origin it was published from)
- URL: https://gamma-api.polymarket.com/events/similar
- Auth: none declared
Query parameters
Event ID. Fastest path: skips the Typesense reference lookup.
Free-text event title to find a reference event in Typesense.
Event slug. Validated as a slug when provided, looked up in PG.
Free-text market title to find a reference event in Typesense.
Market slug. Validated as a slug when provided; the parent event is used as the reference.
Max results returned. Capped at 50.
Optional. When 'true' returns only resolved events; when 'false' returns only open events. When omitted, both are returned. Always combined with the unconditional active=true filter.
Load each event's markets (true/false). Off by default: the response is the slim event list.
With include_markets=true, keep only the N most likely markets per event: open markets first, then by first outcome price descending. 0 (default) keeps every market.
Optional wait budget for vector-search candidates in milliseconds (100 to 5000). Expiry uses the popular-events fallback without cancelling the underlying search, which has a server-owned deadline of at most 5 seconds. When omitted, the configured search deadline applies.
Response
OK
Example response
[
{
"$schema": "https://example.com/schemas/Event.json",
"eventCreators": [
{
"$schema": "https://example.com/schemas/EventCreator.json"
}
],
"externalPartners": [
{
"$schema": "https://example.com/schemas/EventExternalPartnerMapping.json",
"partner": {
"$schema": "https://example.com/schemas/Partner.json"
}
}
],
"markets": [
{
"$schema": "https://example.com/schemas/Market.json",
"cryptoMarketConfig": {
"$schema": "https://example.com/schemas/CryptoMarketConfig.json"
},
"tags": [
{
"$schema": "https://example.com/schemas/Tag.json"
}
]
}
],
"series": [
{
"$schema": "https://example.com/schemas/Series.json"
}
],
"sport": {
"$schema": "https://example.com/schemas/SportsMetadata.json",
"externalPartners": [
{
"$schema": "https://example.com/schemas/SportExternalPartnerMapping.json",
"partner": {
"$schema": "https://example.com/schemas/Partner.json"
}
}
]
},
"tags": [
{
"$schema": "https://example.com/schemas/Tag.json"
}
],
"teams": [
{
"$schema": "https://example.com/schemas/Team.json",
"externalPartners": [
{
"$schema": "https://example.com/schemas/TeamExternalPartnerMapping.json",
"partner": {
"$schema": "https://example.com/schemas/Partner.json"
}
}
]
}
]
}
]Changes
No recorded changes to this operation across all 1 revision of this API.