Markets API

Markets is a premium, generated-report product backed by module-C. There is no free market data: the snapshot returns the panel's CTA/empty state (the available paid analyses and their cost). Routes are served under /v1/markets.

Precondition: market data must exist for the brand. POST /v1/markets/analyze and POST /v1/markets/validate both require pre-existing market data for the brand. Market data is populated automatically by the AI92 platform over time, based on brand activity, product data, and domain signals — there is no API call to seed or bootstrap it. A brand created moments ago (or any brand with no market history) returns 422 MARKETS_NO_DATA from both endpoints, with no credit charge. These endpoints are therefore not testable on a day-one brand: run them on a brand that has been active for at least several days with real domain and product data. If you receive MARKETS_NO_DATA, wait for the platform to populate data for the brand before retrying — the block is time-gated, not a configuration error you can fix in the request.

Authentication

Authorization: Bearer ai92_live_<key>     # production
Authorization: Bearer ai92_test_<key>     # sandbox

Mutating requests support Idempotency-Key and are brand-gated.

Credit costs at a glance

Endpoint	Cost
`GET /v1/markets/snapshot`	Free (CTA / empty state)
`POST /v1/markets/analyze`	45 cr
`POST /v1/markets/validate`	15 cr
`POST /v1/markets/competitor-intel`	25 cr
`POST /v1/markets/predictive`	40 cr

GET /v1/markets/snapshot

Cost: Free

Returns the Markets panel CTA: a list of the available paid analyses and their credit cost. Viewing a report you already generated is free; running an analysis (re)generates it.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand.

Request

bash

curl "https://api.ai92.ai/v1/markets/snapshot?brand_id=acme" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "available": false,
  "premium": true,
  "message": "Market analysis is a premium, generated product. Run an analysis to generate your report; viewing a report you generated is free.",
  "actions": [
    { "action": "analyze", "endpoint": "/v1/markets/analyze", "credits": 45, "label": "Comprehensive market report" },
    { "action": "validate", "endpoint": "/v1/markets/validate", "credits": 15, "label": "Campaign performance validation" },
    { "action": "competitor-intel", "endpoint": "/v1/markets/competitor-intel", "credits": 25, "label": "Competitor intelligence" },
    { "action": "predictive", "endpoint": "/v1/markets/predictive", "credits": 40, "label": "Predictive model" }
  ]
}

POST /v1/markets/analyze

Cost: 45 credits

Generate a comprehensive market report for a brand.

Auth: Bearer

Field	Type	Required	Description
`brand_id`	string	Yes	The brand to analyze.

Request

bash

curl https://api.ai92.ai/v1/markets/analyze \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "acme"}'

Response 200 OK

json

{
  "brand_id": "acme",
  "report_id": "mkt_5521",
  "market_size_usd": 12400000000,
  "growth_rate": 0.11,
  "segments": [ { "name": "SMB", "share": 0.38 } ]
}

Errors

Status	Code	When
`422`	`MARKETS_NO_DATA`	Brand has no market history yet (see Precondition). No credit charge.
`402`	`INSUFFICIENT_CREDITS`	Balance below 45 credits.

POST /v1/markets/validate

Cost: 15 credits

Validate a campaign's performance against market benchmarks.

Auth: Bearer

Requires existing market data for the brand (see Precondition); returns 422 MARKETS_NO_DATA otherwise.

Field	Type	Required	Description
`brand_id`	string	Yes	The brand to validate against.
`market_segment`	string	No	Market segment, e.g. `SMB SaaS`.
`geography`	string	No	Target geography, e.g. `US`.
`campaign_id`	string	No	The campaign to validate, if scoping to one.

Request

bash

curl https://api.ai92.ai/v1/markets/validate \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "acme", "market_segment": "SMB SaaS", "geography": "US"}'

Response 200 OK

json

{
  "campaign_id": "camp_77a2",
  "benchmark_percentile": 72,
  "verdict": "above_market",
  "metrics": { "ctr": 0.034, "market_ctr": 0.021 }
}

Errors

Status	Code	When
`422`	`MARKETS_NO_DATA`	Brand has no market history yet (see Precondition). No credit charge.
`402`	`INSUFFICIENT_CREDITS`	Balance below 15 credits.

POST /v1/markets/competitor-intel

Cost: 25 credits

Competitor intelligence report: ad spend, channels, strategies, and share-of-voice estimates.

Auth: Bearer

Field	Type	Required	Description
`primary_brand`	string	Yes	Your brand.
`competitor_brands`	string[]	Yes	Competitors to analyze. Length `1`–`10`.
`channels`	string[] / null	No	Restrict to specific channels.

Request

bash

curl https://api.ai92.ai/v1/markets/competitor-intel \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"primary_brand": "acme", "competitor_brands": ["rival", "northwind"], "channels": ["search", "social"]}'

Response 200 OK

json

{
  "primary_brand": "acme",
  "competitors": [
    { "brand": "rival", "est_ad_spend_usd": 480000, "share_of_voice": 0.27, "top_channels": ["search", "social"] }
  ]
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 25 credits.

POST /v1/markets/predictive

Cost: 40 credits

AI-driven forecast for a metric over a time horizon.

Auth: Bearer

Field	Type	Required	Description
`brand_id`	string	Yes	The brand.
`horizon_days`	integer	No	Forecast horizon. Default `30`. Range `7`–`365`.
`metric`	string	No	Metric to forecast. Default `roas`.

Request

bash

curl https://api.ai92.ai/v1/markets/predictive \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "acme", "horizon_days": 90, "metric": "roas"}'

Response 200 OK

json

{
  "brand_id": "acme",
  "metric": "roas",
  "horizon_days": 90,
  "forecast": [ { "date": "2026-07-01", "value": 3.4, "ci_low": 2.9, "ci_high": 3.9 } ]
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 40 credits.