V4MOS.AI API
GuidesAPI Referenceapp.v4mos.ai
Acquisition

Get Paid Media Audience

GET
/v1/acquisition/paid-media/audience

Meta Ads audience and regions: investment, leads and cost per lead by gender and age range, and reach and cost by region.

Use it to understand who Meta ads reach and where. Meta Ads only.

  • Leads are Meta's lead event, without the funnel's event selection. That is why they do not match /v1/acquisition/paid-media, which also adds CRM and Google Ads leads.
  • genders always holds female, male and unknown, in that order. ages lists the age ranges with spend or a lead, youngest first, with unknown last.
  • regions lists the regions (states) with reach, most reached first. Reach is an approximation summed per ad and day, and regions carry no leads.
  • hasMeta: false: the organization has no Meta Ads data and every list is empty. hasLeads: false: the period's data carries no lead information, so leads, cpl and leadsByGender are null.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Query Parameters

organizationId*string

Organization identifier (required). A missing or non-string value is a 400.

period?stringDeprecated

Deprecated: use startDate and endDate, which take precedence when sent. Relative period of N days ending today, inclusive (7d = today and the 6 days before it). "Today" is the UTC calendar day, and that last day is still partial. Accepted values: 7d, 30d, 90d, 1y. Omitted or empty means 30d; any other value returns 400.

Default"30d"
Value in"7d""30d""90d""1y"
startDate?string

Start of the period (YYYY-MM-DD, inclusive). Send it together with endDate: sending only one of them returns 400. Takes precedence over period. Send the date only: a date with a time or a date that does not exist returns 400. Rules: startDate ≤ endDate, neither date in the future (UTC), and at most 365 days between the dates (up to 366 days in the period). The comparison uses the period of the same length right before it.

Formatdate
endDate?string

End of the period (YYYY-MM-DD, inclusive). See startDate for the rules. When the end date is today, that last day is still partial, because the day's data keeps arriving.

Formatdate

Response Body

Paid media audience and regions returned successfully

application/json
  1. response
hasMeta*boolean
hasLeads*boolean
genders*array<>
ages*array<>
regions*array<>
curl -X GET "https://example.com/v1/acquisition/paid-media/audience?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&period=30d&startDate=2026-03-11&endDate=2026-03-22"
{  "hasMeta": true,  "hasLeads": true,  "genders": [    {      "gender": "female",      "investment": 5238.38,      "leads": 217,      "cpl": 24.14    },    {      "gender": "male",      "investment": 5856.58,      "leads": 206,      "cpl": 28.43    },    {      "gender": "unknown",      "investment": 28.44,      "leads": 2,      "cpl": 14.22    }  ],  "ages": [    {      "ageRange": "18-24",      "investment": 182.36,      "leads": 4,      "cpl": 45.59,      "leadsByGender": {        "female": 1,        "male": 3,        "unknown": 0      }    },    {      "ageRange": "65+",      "investment": 1662.86,      "leads": 94,      "cpl": 17.69,      "leadsByGender": {        "female": 52,        "male": 42,        "unknown": 0      }    }  ],  "regions": [    {      "region": "São Paulo",      "country": "BR",      "reach": 26300,      "investment": 2766.5,      "costPerThousandReach": 105.19    }  ]}

Get Paid Media Overview GET

Previous Page