Search deals with AI-friendly filters
Operation
GET
/deals
Advanced deal search for deals, offers, coupons, and promotions. Prefer q or query for free-form lookup, especially for natural-language requests like 'show me exclusive Alo Yoga deals', or use structured filters when you already know the advertiser, network, country, or activity constraints. GraphQL alternative: POST /graphql (`deals` / `deal`) via operationId executeGraphql — visible deals only by default (`hidden: false`); pass `includeHidden: true` on `deals` to include authorized hidden deals.
listDeals
·
Tags: Deals
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
q
|
query | No | string | Preferred free-form query. Searches deal names plus indexed advertiser, campaign, and country fields, and can infer simple flags like exclusive or featured from natural language. |
query
|
query | No | string | Alias for q. |
search
|
query | No | string | Explicit deal search text. Prefer q unless you need to force the text-search field. |
advertiser_id
|
query | No | string | Advertiser ID or slug filter |
advertiser_domain
|
query | No | string | Advertiser public domain filter (e.g. amazon.com) |
network_id
|
query | No | string | Network ID or slug filter |
vertical_id
|
query | No | string | Vertical ID filter |
country
|
query | No | string | Country filter (ISO code). Scalar only — `country[]=US` is rejected. |
country_code
|
query | No | string | Alias for country. |
exclusive
|
query | No | boolean | Exclusive deals filter |
active
|
query | No | boolean | Active deals filter |
featured
|
query | No | boolean | Featured deals filter |
status
|
query | No | string | Deal activity status filter. |
deal_type
|
query | No | string | Filter deals by kind. Public-facing alias of deal_kind. Use GET /deals/types to discover supported values. |
deal_kind
|
query | No | string | Legacy alias for deal_type. Both are accepted; deal_type wins if both are sent. |
device
|
query | No | string | Filter deals by device targeting. |
deal_visibility
|
query | No | string | Opt into hidden deals. Omit (default) for visible-only; "hidden" returns only hidden rows. Authorization is still enforced by policy_scope. |
limit
|
query | No | integer | Upper bound for per_page. |
page
|
query | No | integer | Page number |
per_page
|
query | No | integer | Results per page |
include_total
|
query | No | boolean | Include exact total counts in the meta payload. |
include_count
|
query | No | boolean | Alias flag used by some list endpoints for count metadata. |
dry_run
|
query | No | boolean | Validate params without executing the search when supported |
Request Body
No request body is defined for this operation.
Responses
Content Types
application/json
{
"description": "Deals list wrapped under `deals` with offset pagination meta",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"deals": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"example": "deal"
},
"attributes": {
"$ref": "#/components/schemas/Deal"
}
}
}
}
},
"required": [
"data"
]
},
"meta": {
"$ref": "#/components/schemas/AdvertiserOffsetMeta"
}
},
"required": [
"deals",
"meta"
]
}
}
}
}{
"$ref": "#/components/responses/BadRequest"
}{
"$ref": "#/components/responses/Unauthorized"
}{
"$ref": "#/components/responses/RateLimited"
}API Playground
Run this GET request with your API key, or open it in a new tab. Path uses sample IDs where the OpenAPI path has {parameters}.
Sign in to enable live testing with your API key.
| Action | Method | Endpoint | Description |
|---|---|---|---|
| Search deals with AI-friendly filters | GET |
/api/v1/deals |
OpenAPI operationId: listDeals. |
GET /api/v1/deals
OpenAPI
Search deals with AI-friendly filters