Pular para o conteúdo

POST /v1/analytics/marketing/ads/search

POST
/v1/analytics/marketing/ads/search
curl --request POST \
--url https://seu-endereco-da-api/v1/analytics/marketing/ads/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "period": "7", "window": "current", "adAccountId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "filter": {} }'

Leads, conversations, deals and revenue use the days of the window in America/Sao_Paulo, including the partial current day. Meta’s spend is requested for those same days (time_range since/until), which Meta reads in each connected ad account’s own timezone (AdAccount.timezone). When an account is not on America/Sao_Paulo the two windows can still differ by a few hours at the edges, and every derived figure (costPerLead, costPerConversation, roas) inherits that skew.

Permissão que a Chave de acesso precisa: Relatórios de marketing (analytics:marketing).

Media typeapplication/json
object
period
string
Allowed values: 7 30 90
window
string
Allowed values: current previous
adAccountId
string format: uuid
filter
object
key
additional properties
any
Media typeapplication/json
object
connected
required
boolean
adsAvailable
required

True only when every connected ad account’s Meta insights fetch succeeded this call (live or cached); false on no connected account, an expired token, or any Graph error, even if some accounts succeeded

boolean
currency
required

ISO 4217 currency code shared by all connected ad accounts; null when there are no connected accounts or they use different currencies (no FX conversion is performed)

string
nullable
ads
required
Array<object>
object
sourceId
required
string
headline
required
string
nullable
sourceApp
required
string
nullable
thumbUrl
required
string
nullable
leads
required
number
conversations
required
number
deals
required
number
revenue
required
number
spend
required

Spend in cents, in this ad’s own currency (see currency below); null when Meta has no data for this ad, or when the fetch was only partially successful

number
nullable
currency
required

ISO 4217 currency code of the ad account this ad’s spend came from; null when spend is null. Can differ row to row when the report is unfiltered and connected accounts disagree on currency — use this, not the top-level currency, to label each row

string
nullable
impressions
required

Raw Meta impressions for this ad in the period; null when unavailable

number
nullable
clicks
required

Raw Meta clicks for this ad in the period; null when unavailable

number
nullable
reach
required

Raw Meta reach for this ad in the period; null when unavailable

number
nullable
costPerLead
required

Spend in cents divided by leads; null when spend is unknown or leads is zero

number
nullable
costPerConversation
required

Spend in cents divided by conversations; null when spend is unknown or conversations is zero

number
nullable
roas
required

Revenue divided by spend, rounded to 2 decimal places (e.g. 2.5 means 2.5x return); null when spend is unknown or zero

number
nullable
firstLeadAt

Absent (not null) when this ad brought zero leads in the period

string format: date-time
lastLeadAt

Absent (not null) when this ad brought zero leads in the period

string format: date-time
totals
required
object
leads
required
number
conversations
required
number
deals
required
number
revenue
required
number
spend
required

Sum of spend across ads with known spend only; null unless every connected account’s fetch succeeded AND at least one ad has known spend; also null when connected accounts disagree on currency, since a sum across currencies would be meaningless — see currency

number
nullable
costPerLead
required

Computed only over ads with known spend: leads/conversations/revenue in this ratio come from knownSpendScope, NOT from leads/conversations/revenue above, so totals.leads * costPerLead will not equal totals.spend by design — render the knownSpendScope caveat alongside this figure

number
nullable
costPerConversation
required

Same known-spend-only scoping as costPerLead; see knownSpendScope

number
nullable
roas
required

Revenue/spend rounded to 2 decimal places, computed only over ads with known spend; see knownSpendScope

number
nullable
knownSpendScope
required

The exact subset of ads/leads/conversations/revenue/spend that costPerLead, costPerConversation and roas were computed over, so a caveat like ‘computed over N of M leads’ can be rendered instead of leaving the mismatch unexplained

object
ads
required

How many of the ads[] rows have a known spend and were counted below

number
leads
required

Leads summed over only the ads with known spend; will be less than totals.leads whenever ads is less than ads[].length

number
conversations
required

Conversations summed over only the ads with known spend

number
revenue
required

Revenue summed over only the ads with known spend

number
spend
required

Spend in cents summed over only the ads with known spend; same value as totals.spend, including null when the connected accounts disagree on currency and the sum would mix currencies

number
nullable

Example generated

{
"connected": true,
"adsAvailable": true,
"currency": "example",
"ads": [
{
"sourceId": "example",
"headline": "example",
"sourceApp": "example",
"thumbUrl": "example",
"leads": 1,
"conversations": 1,
"deals": 1,
"revenue": 1,
"spend": 1,
"currency": "example",
"impressions": 1,
"clicks": 1,
"reach": 1,
"costPerLead": 1,
"costPerConversation": 1,
"roas": 1,
"firstLeadAt": "2026-04-15T12:00:00Z",
"lastLeadAt": "2026-04-15T12:00:00Z"
}
],
"totals": {
"leads": 1,
"conversations": 1,
"deals": 1,
"revenue": 1,
"spend": 1,
"costPerLead": 1,
"costPerConversation": 1,
"roas": 1,
"knownSpendScope": {
"ads": 1,
"leads": 1,
"conversations": 1,
"revenue": 1,
"spend": 1
}
}
}