Introduction

Get started with the Adverfly API

The Adverfly API allows you to programmatically access data from your workspace. You can retrieve events, sessions, conversions, and ads for analytics.

API Capabilities

Capability	Description
Read Data	Retrieve events, sessions, conversions, and ads via GET endpoints

When to Use the API vs. JavaScript Pixel

Use Case	Recommended Method
Website tracking	JavaScript Pixel (client-side)
Data export / BI integration	API
Custom dashboards	API
Real-time web analytics	JavaScript Pixel

Base URL

All API requests should be made to:

BASEhttps://api.adverfly.com

Authentication

The API uses API keys for authentication. You can generate API credentials in your workspace settings.

Parameter	Type	Required	Description
`x-api-key`	string	Required	Your workspace API key
`client-secret`	string	Required	Your workspace client secret

Request

curl -X GET "https://api.adverfly.com/v3/events" \
  -H "x-api-key: your-api-key" \
  -H "client-secret: your-client-secret"

Response Format

All responses are returned in JSON format with a pagination object for navigating results.

Response200 OK

{
  "data": [...],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Pagination

Field	Type	Description
`limit`	integer	Number of records returned
`offset`	integer	Number of records skipped
`has_more`	boolean	Whether more records are available
`next_offset`	integer or null	Offset value for the next page (null when `has_more` is false)
`start_date`	string	Start of the queried date range
`end_date`	string	End of the queried date range

Use next_offset as the offset parameter in your next request to paginate through results. When has_more is false, you have reached the last page.

Rate Limits

Limit	Value
Daily quota	4,320 requests per day
Rate limit	10 requests per second
Burst limit	20 requests
Max records per request	500 (`limit` parameter)

Date Parameters

All endpoints accept start_date and end_date in YYYY-MM-DD format. If omitted, the API defaults to the last 7 days. Aliases from and to are also accepted.

Events

Retrieve event data from your workspace

Retrieve event data from your workspace pixel tracking. Events include pageviews, clicks, and custom events tracked by your pixel.

GET/v3/events

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Optional	Start date in YYYY-MM-DD format (default: 7 days ago). Alias: from
`end_date`	string	Optional	End date in YYYY-MM-DD format (default: today). Alias: to
`name`	string	Optional	Filter by event name. Supports wildcards with * (e.g. survey_* to match all survey events). Alias: event_name
`session_id`	integer	Optional	Filter by session ID
`visitor_id`	integer	Optional	Filter by visitor ID
`source`	string	Optional	Filter by ad source. Comma-separated for multiple (e.g. meta,google). Alias: sources
`limit`	integer	Optional	Number of records to return (default: 100, max: 500). Alias: page_size
`offset`	integer	Optional	Number of records to skip for pagination. Alias: page

Name filter examples

Value	Matches
`pageview`	Exact match — only `pageview` events
`survey_*`	All events starting with `survey_` (e.g. `survey_opened`, `survey_completed`)
`*_completed`	All events ending with `_completed`

Request

curl -X GET "https://api.adverfly.com/v3/events?start_date=2024-01-01&end_date=2024-01-31&name=survey_*&limit=100" \
  -H "x-api-key: your-api-key" \
  -H "client-secret: your-client-secret"

Response200 OK

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15 10:30:00",
      "name": "pageview",
      "session_id": 789012345,
      "visitor_id": 456789012,
      "visitor_timezone": "Europe/Berlin",
      "adv_source": "meta",
      "adv_campaign_id": "120210123456789",
      "adv_adgroup_id": "120210987654321",
      "adv_ad_id": "120210111222333",
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "winter_sale",
      "utm_content": "video_ad_1",
      "utm_term": "",
      "device_type": "desktop",
      "country_code": "DE",
      "hostname": "example.com",
      "pathname": "/products",
      "referrer": "https://google.com",
      "entry_meta_keys": ["fbclid", "gclid"],
      "entry_meta_values": ["abc123", ""]
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Response Fields

Field	Type	Description
`store_id`	integer	Workspace ID
`dt`	string	Event timestamp
`name`	string	Event name (e.g. `pageview`, `add_to_cart`, `survey_opened`)
`session_id`	integer	Session identifier
`visitor_id`	integer	Visitor identifier
`visitor_timezone`	string	Visitor's timezone
`adv_source`	string	Ad platform source (e.g. `meta`, `google`)
`adv_campaign_id`	string	Campaign ID from ad platform
`adv_adgroup_id`	string	Ad group ID from ad platform
`adv_ad_id`	string	Ad ID from ad platform
`utm_source`	string	UTM source parameter
`utm_medium`	string	UTM medium parameter
`utm_campaign`	string	UTM campaign parameter
`utm_content`	string	UTM content parameter
`utm_term`	string	UTM term parameter
`device_type`	string	Device type (desktop, mobile, tablet)
`country_code`	string	ISO country code (e.g. DE, US)
`hostname`	string	Website hostname
`pathname`	string	Page path
`referrer`	string	Referring URL
`entry_meta_keys`	array	Click ID parameter names (e.g. fbclid, gclid)
`entry_meta_values`	array	Click ID values (parallel array with entry_meta_keys)

Sessions

Access session data and user activity

Access session data and user activity information. A session represents a user's visit to your website, grouping multiple events together.

GET/v3/sessions

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Optional	Start date in YYYY-MM-DD format (default: 7 days ago). Alias: from
`end_date`	string	Optional	End date in YYYY-MM-DD format (default: today). Alias: to
`session_id`	integer	Optional	Filter by session ID
`visitor_id`	integer	Optional	Filter by visitor ID
`source`	string	Optional	Filter by ad source. Comma-separated for multiple. Alias: sources
`limit`	integer	Optional	Number of records to return (default: 100, max: 500). Alias: page_size
`offset`	integer	Optional	Number of records to skip for pagination. Alias: page

Request

curl -X GET "https://api.adverfly.com/v3/sessions?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
  -H "x-api-key: your-api-key" \
  -H "client-secret: your-client-secret"

Response200 OK

{
  "data": [
    {
      "store_id": 12345,
      "visitor_id": 456789012,
      "session_id": 789012345,
      "session_start_dt": "2024-01-15 10:25:00",
      "session_end_dt": "2024-01-15 10:45:00",
      "session_duration_seconds": 1200,
      "is_bounce": 0,
      "session_entry_page": "/",
      "session_exit_page": "/checkout/success",
      "events": 12,
      "pageviews": 8,
      "add_to_carts": 1,
      "initiated_checkouts": 1,
      "view_contents": 3,
      "contacts": 0,
      "newsletter_signups": 0,
      "completed_registrations": 0,
      "app_installs": 0,
      "add_payment_infos": 1,
      "adv_source": "meta",
      "adv_campaign_id": "120210123456789",
      "adv_adgroup_id": "120210987654321",
      "adv_ad_id": "120210111222333",
      "utm_source": "facebook",
      "utm_campaign": "winter_sale",
      "utm_medium": "cpc",
      "utm_content": "video_ad_1",
      "utm_term": "",
      "device_type": "desktop",
      "country_code": "DE",
      "referrer": "https://google.com",
      "pathname": "/products",
      "hostname": "example.com",
      "entry_meta_keys": ["fbclid"],
      "entry_meta_values": ["abc123"]
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Response Fields

Field	Type	Description
`store_id`	integer	Workspace ID
`visitor_id`	integer	Visitor identifier
`session_id`	integer	Session identifier
`session_start_dt`	string	Session start timestamp
`session_end_dt`	string	Session end timestamp
`session_duration_seconds`	integer	Session duration in seconds
`is_bounce`	integer	Whether the session was a bounce (1 = bounce, 0 = not)
`session_entry_page`	string	Landing page path
`session_exit_page`	string	Exit page path
`events`	integer	Total number of events in session
`pageviews`	integer	Number of page views
`add_to_carts`	integer	Number of add-to-cart events
`initiated_checkouts`	integer	Number of checkout starts
`view_contents`	integer	Number of content views
`contacts`	integer	Number of contact events
`newsletter_signups`	integer	Number of newsletter signups
`completed_registrations`	integer	Number of completed registrations
`app_installs`	integer	Number of app installs
`add_payment_infos`	integer	Number of payment info submissions
`adv_source`	string	Ad platform source
`adv_campaign_id`	string	Campaign ID from ad platform
`adv_adgroup_id`	string	Ad group ID from ad platform
`adv_ad_id`	string	Ad ID from ad platform
`utm_source`	string	UTM source parameter
`utm_campaign`	string	UTM campaign parameter
`utm_medium`	string	UTM medium parameter
`utm_content`	string	UTM content parameter
`utm_term`	string	UTM term parameter
`device_type`	string	Device type (desktop, mobile, tablet)
`country_code`	string	ISO country code
`referrer`	string	Referring URL
`pathname`	string	Page path
`hostname`	string	Website hostname
`entry_meta_keys`	array	Click ID parameter names
`entry_meta_values`	array	Click ID values

Conversions

Get conversion event data

Get conversion event data for your workspace. Conversions are tracked when users complete desired actions like purchases, signups, or form submissions.

GET/v3/conversions

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Optional	Start date in YYYY-MM-DD format (default: 7 days ago). Alias: from
`end_date`	string	Optional	End date in YYYY-MM-DD format (default: today). Alias: to
`name`	string	Optional	Filter by conversion name. Supports wildcards with * (e.g. purchase_*)
`transaction_id`	string	Optional	Filter by transaction/order ID
`customer_id`	string	Optional	Filter by customer ID
`is_new_customer`	string	Optional	Filter by new/returning customer (accepts 0, 1, true, false)
`limit`	integer	Optional	Number of records to return (default: 100, max: 500). Alias: page_size
`offset`	integer	Optional	Number of records to skip for pagination. Alias: page

Request

curl -X GET "https://api.adverfly.com/v3/conversions?start_date=2024-01-01&end_date=2024-01-31&limit=100" \
  -H "x-api-key: your-api-key" \
  -H "client-secret: your-client-secret"

Response200 OK

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15 10:42:00",
      "name": "purchase",
      "session_id": 789012345,
      "customer_id": "customer@email.com",
      "visitor_id": 456789012,
      "transaction_id": "ORD-2024-001",
      "transaction_gross_revenue": 12999,
      "transaction_currency": "EUR",
      "transaction_country_code": "DE",
      "transaction_city": "Berlin",
      "hostname": "example.com"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59"
  }
}

Response Fields

Field	Type	Description
`store_id`	integer	Workspace ID
`dt`	string	Conversion timestamp
`name`	string	Conversion type (e.g. `purchase`, `lead`)
`session_id`	integer	Session identifier
`customer_id`	string	Customer identifier (e.g. email)
`visitor_id`	integer	Visitor identifier
`transaction_id`	string	Order/transaction ID
`transaction_gross_revenue`	integer	Revenue in cents (e.g. 12999 = 129.99)
`transaction_currency`	string	Currency code (EUR, USD, etc.)
`transaction_country_code`	string	ISO country code
`transaction_city`	string	Customer's city
`hostname`	string	Website hostname

Notes

Revenue is returned in the smallest currency unit (cents). Divide by 100 for the main currency value.
Use transaction_id or customer_id filters to look up specific orders or customers.

Get advertising performance data

Get advertising performance data for your workspace. Returns spend, impressions, clicks, and reach from connected ad platforms (Meta, Google, TikTok, etc.).

GET/v3/ads

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Optional	Start date in YYYY-MM-DD format. Defaults to 7 days ago if omitted.
`end_date`	string	Optional	End date in YYYY-MM-DD format. Defaults to today if omitted.
`source`	string	Optional	Filter by ad platform. Comma-separated for multiple (e.g. meta,google)
`adaccount_id`	string	Optional	Filter by ad account ID
`campaign_id`	string	Optional	Filter by campaign ID
`adgroup_id`	string	Optional	Filter by ad group ID
`ad_id`	string	Optional	Filter by ad ID
`limit`	integer	Optional	Number of records to return (default: 100)
`offset`	integer	Optional	Number of records to skip for pagination

Supported sources

Value	Platform
`meta`	Meta (includes facebook, instagram, messenger, audience_network, threads)
`facebook`	Facebook (subset of Meta)
`instagram`	Instagram (subset of Meta)
`google`	Google Ads
`tiktok`	TikTok Ads
`pinterest`	Pinterest Ads
`snapchat`	Snapchat Ads
`outbrain`	Outbrain
`taboola`	Taboola
`organic`	Organic traffic
`audience_network`	Meta Audience Network (subset of Meta)
`messenger`	Meta Messenger (subset of Meta)
`threads`	Meta Threads (subset of Meta)
`whatsapp`	WhatsApp
`email`	Email channels

Request

curl -X GET "https://api.adverfly.com/v3/ads?start_date=2024-01-01&end_date=2024-01-31&source=meta,google&limit=100" \
  -H "x-api-key: your-api-key" \
  -H "client-secret: your-client-secret"

Response200 OK

{
  "data": [
    {
      "store_id": 12345,
      "dt": "2024-01-15",
      "adaccount_id": "act_123456789",
      "source": "meta",
      "campaign_id": "120210123456789",
      "campaign_name": "Winter Sale 2024",
      "adgroup_id": "120210987654321",
      "adgroup_name": "Lookalike - Purchases",
      "ad_id": "120210111222333",
      "ad_name": "Video - Snow Jacket",
      "spend": 4500,
      "impressions": 12340,
      "clicks": 287,
      "reach": 9800
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true,
    "next_offset": 100,
    "start_date": "2024-01-01 00:00:00",
    "end_date": "2024-01-31 23:59:59",
    "sources": ["meta", "google"]
  }
}

Response Fields

Field	Type	Description
`store_id`	integer	Your workspace ID
`dt`	string	Date of the ad data (YYYY-MM-DD)
`adaccount_id`	string	Ad account identifier
`source`	string	Ad platform (meta, google, tiktok, etc.)
`campaign_id`	string	Campaign identifier
`campaign_name`	string	Campaign name
`adgroup_id`	string	Ad group identifier
`adgroup_name`	string	Ad group name
`ad_id`	string	Ad identifier
`ad_name`	string	Ad name
`spend`	integer	Spend in smallest currency unit (cents)
`impressions`	integer	Number of impressions
`clicks`	integer	Number of clicks
`reach`	integer	Number of unique users reached (0 if not reported by platform)

Totals

The ads endpoint also returns a totals object at the top level with aggregated values:

{
  "totals": {
    "total_ads": 500,
    "total_spend": 123456,
    "total_impressions": 9876543,
    "total_clicks": 54321,
    "total_reach": 7654321
  },
  "data": [...],
  "pagination": { ... }
}

Notes

Spend is returned in the smallest currency unit (e.g. cents). Divide by 100 to get the value in the main currency unit.
Reach may be 0 for platforms that do not report it (e.g. Google Ads).
Data is deduplicated per ad per day. If the same ad data is imported multiple times, only the latest version is returned.
Requires read:<source> or admin:admin permission on your API key.

Errors

API error codes and handling

The Adverfly API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Status Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Missing required headers or invalid parameters
401	Unauthorized	Invalid API key or client secret
403	Forbidden	Valid credentials but insufficient permissions for the requested source
404	Not Found	Requested endpoint does not exist
405	Method Not Allowed	HTTP method not supported
429	Too Many Requests	Rate limit exceeded (enforced at API Gateway level)
500	Internal Server Error	Unexpected server error

Error Response Format

When an error occurs, the API returns a JSON object with a message field:

Response401 Unauthorized

{
  "message": "Invalid API key"
}

Common Error Messages

Code	Description
`Missing x-api-key header`	The x-api-key header was not included in the request (HTTP 400)
`Missing client-secret header`	The client-secret header was not included in the request (HTTP 400)
`Invalid API key`	The provided API key does not exist or has been revoked (HTTP 401)
`Invalid client secret`	The client secret does not match the API key (HTTP 401)
`You do not have access to pixel data`	Your API key does not have pixel read permissions (HTTP 403)
`You do not have access to ads data`	Your API key does not have ads read permissions (HTTP 403)
`You do not have access to the requested sources`	Your API key lacks permission for one or more of the requested source platforms (HTTP 403)
`Invalid start_date or end_date parameter`	Date must be in YYYY-MM-DD format (HTTP 400)
`start_date must be before end_date`	The start date is after the end date (HTTP 400)
`limit must be a positive integer`	The limit parameter must be a positive number (HTTP 400)
`offset must be a non-negative integer`	The offset parameter cannot be negative (HTTP 400)
`session_id must be numeric`	The session_id filter must be a number (HTTP 400)
`visitor_id must be numeric`	The visitor_id filter must be a number (HTTP 400)
`is_new_customer must be one of 0,1,true,false`	Invalid value for is_new_customer filter (HTTP 400)
`Method not allowed`	The HTTP method used is not supported — use GET (HTTP 405)

Permissions

API keys use a source-based permission system. Each key can have permissions like read:meta, read:google, etc. Use admin:admin for full access to all sources.

If you request ads from a source your key does not have permission for, you will receive a 403 Forbidden response.

Introduction

API Capabilities

When to Use the API vs. JavaScript Pixel

Base URL

Authentication

Response Format

Pagination

Rate Limits

Date Parameters

Events

Query Parameters

Name filter examples

Response Fields

Sessions

Query Parameters

Response Fields

Conversions

Query Parameters

Response Fields

Notes

Ads

Query Parameters

Supported sources

Response Fields

Totals

Notes

Errors

HTTP Status Codes

Error Response Format

Common Error Messages

Permissions