Skip to main content
GET
Fetch ads currently serving for a workspace

Path Parameters

workspaceId
string
required

Workspace ID to serve ads for.

Query Parameters

weight
object

Tier-weight range filter for placement targeting, e.g. weight[gte]=2.5 (premium), weight[lt]=2.5 (regular), or a band weight[gte]=2.5&weight[lt]=5.

tierId

Only serve ads from this tier, or any tier in a set — a fixed slot backed by specific tiers (deterministic complement to weight). Single id or comma-joined set.

excludeIds
string[]

Ad IDs to exclude for dedupe across slots. Comma-joined string or array.

count
number
default:1

Number of distinct ads to return. Clamped to 1–50 (out-of-range values are clamped, not rejected).

Response

OK

ads
object[]
required

Ads eligible to serve now, in rotation order; empty when none are eligible.