Ads - V4 Marketing API

GET

https://api.data.v4.marketing/v1/facebook/ads/ad

Retrieve detailed Facebook Ad level performance metrics with enhanced quality and ranking indicators.

This endpoint provides granular ad-level insights including quality rankings, engagement metrics, and detailed performance indicators.

Dimensions Available:

Ad ID, adset ID, ad name

Metrics: impressions, reach, frequency, clicks, CTR, inline link clicks, spend, CPC, CPM, website purchase ROAS

Quality rankings: quality_ranking, engagement_rate_ranking, conversion_rate_ranking

Actions data (JSON)

Date range (date_start, date_stop)

Limitations:

Maximum 5000 records per page

Supports date filtering via dateStart and dateEnd (ISO 8601 format)

Supports sorting via orderBy and orderDirection (ASC/DESC)

Filters:

workspaceId (required)

organizationId (optional)

userId (optional)

integrationName (optional)

dateStart (optional)

dateEnd (optional)

Requisição

Authorization

API Key

Adicionar parâmetro em header

x-client-id

Exemplo:

x-client-id: ********************

API Key

Adicionar parâmetro em header

x-client-secret

Exemplo:

x-client-secret: ********************

Parâmetros de Consulta

Respostas

🟢200Sucesso

application/json

Successful response

Body

🟠400400

🔴500500

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.data.v4.marketing/v1/facebook/ads/ad?workspaceId=workspace_123&organizationId&userId&integrationName&dateStart=2024-01-01&dateEnd=2024-12-31&page&limit&orderBy&orderDirection' \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>'

Response Example

200 - Exemplo 1

{
    "data": [
        {
            "ad_id": "string",
            "adset_id": "string",
            "ad_name": "string",
            "impressions": 0,
            "reach": 0,
            "frequency": 0,
            "clicks": 0,
            "ctr": 0,
            "inline_link_clicks": 0,
            "inline_link_click_ctr": 0,
            "spend": 0,
            "cpc": 0,
            "cpm": 0,
            "quality_ranking": "string",
            "engagement_rate_ranking": "string",
            "conversion_rate_ranking": "string",
            "website_purchase_roas": 0,
            "date_start": "2019-08-24",
            "date_stop": "2019-08-24",
            "actions": "string",
            "workspace_id": "string",
            "organization_id": "string",
            "user_id": "string",
            "document_id": "string",
            "integration_name": "string",
            "inserted_at": "2019-08-24T14:15:22.123Z"
        }
    ],
    "meta": {
        "page": 0,
        "limit": 0,
        "hasNextPage": true,
        "hasPreviousPage": true
    }
}

Modificado em 2025-12-02 02:02:03