Skip to main content
GET
/
v1
/
marketing
/
promo-intelligence
Analyze promotional activity in a category
curl --request GET \
  --url https://api.syntalic.com/v1/marketing/promo-intelligence \
  --header 'Content-Type: application/json' \
  --data '
{
  "category": "electronics",
  "country": "us",
  "brand": "Apple",
  "aggregate_by": "retailer",
  "from": "2026-04-01",
  "to": "2026-05-01"
}
'
{}

Query Parameters

​
category
string
required

Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with category_id if you have a deterministic id from a prior call.

Minimum string length: 1
​
country
enum<string>
default:us

Country (us or ca)

Available options:
us,
ca
​
brand
string

Optional brand filter — limit aggregation to products of this brand (case-insensitive)

Minimum string length: 1
​
aggregate_by
enum<string>
default:brand

Group-by dimension. brand (default) ranks brands within the category. retailer ranks retailers — pair with brand to answer 'which retailers run the deepest promos on Brand X'.

Available options:
brand,
retailer
​
from
string<date>

Start date (ISO 8601, defaults to 30 days ago)

​
to
string<date>

End date (ISO 8601, defaults to now)

Body

application/json

Query parameters as JSON (alternative to URL query string for agents that prefer body-based invocation).

​
category
string
required

Product category (e.g., electronics, grocery, beauty). Fuzzy human-readable input — the resolver maps it through tier 1-4 (id → exact name → trigram → embedding kNN) to a canonical category_id. Pair with category_id if you have a deterministic id from a prior call.

Minimum string length: 1
Example:

"electronics"

​
country
enum<string>
default:us

Country (us or ca)

Available options:
us,
ca
Example:

"us"

​
brand
string

Optional brand filter — limit aggregation to products of this brand (case-insensitive)

Minimum string length: 1
Example:

"Apple"

​
aggregate_by
enum<string>
default:brand

Group-by dimension. brand (default) ranks brands within the category. retailer ranks retailers — pair with brand to answer 'which retailers run the deepest promos on Brand X'.

Available options:
brand,
retailer
Example:

"retailer"

​
from
string<date>

Start date (ISO 8601, defaults to 30 days ago)

Example:

"2026-04-01"

​
to
string<date>

End date (ISO 8601, defaults to now)

Example:

"2026-05-01"

Response

Promo intelligence

The response is of type object.