REST API

Adspect provides a REST API for automating various tasks:

Creating, editing, and deleting streams
Downloading integration PHP files
Managing guest access to reporting
Creating reports: building sales funnels and retrieving click logs

The base URL for all API endpoints is https://api.adspect.net/v1/. Endpoint descriptions below specify paths relative to this base URL. HTTP method (verb) comes first, followed by the relative endpoint path, for example:

GET /streams

This endpoint description means making a GET request to https://api.adspect.net/v1/streams.

The API supports JSON and XML data encoding. Examples below use JSON encoding for simplicity.

Authentication

Adspect API employs HTTP Basic authentication scheme in which API key is supplied as username and password is left blank. You may find your API key in your profile.

Each API request must contain two mandatory headers:

:::{list-table} :header-rows: 1

- Header
- Value
- Description
- Authorization
- Basic AUTHKEY
- Authenticate for an Adspect account with its API key (see below.)
- Content-Type
- application/json or application/xml
- Select JSON or XML data encoding, respectively. :::

The AUTHKEY placeholder in the Authorization header must be replaced by a base64-encoded string composed of the API key and a colon appended to it.

Example code in PHP:

:emphasize-lines: 3
:lineno-start: 1

<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$authKey = base64_encode($apiKey . ':');

:::{tip} For convenience, there's a readily encoded value of AUTHKEY available in your profile in the Authorization Header field. :::

Some HTTP clients offer native support for HTTP Basic authentication scheme which will set the Authorization header for you (e.g. Python Requests provides the requests.auth.HTTPBasicAuth class.) In this case pass your API key for username and leave password blank. Example for php-curl:

<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$curl = curl_init();
curl_setopt($curl, CURLOPT_USERPWD, $apiKey . ':');

Collections

Certain object properties may take values only from concrete finite sets--collections. The table below lists collection endpoints:

:::{list-table} :header-rows: 1

- GET /collections/presets
- Presets for various traffic sources when creating streams.
- GET /collections/os
- Operating systems for targeting and reporting.
- GET /collections/browsers
- Browsers for targeting and reporting.
- GET /collections/engines
- Browser engines for targeting and reporting.
- GET /collections/countries
- Country codes for targeting and reporting.
- GET /collections/languages
- Language codes for targeting and reporting.
- GET /collections/time-zones
- Time zones for targeting and reporting.
- GET /collections/stream-modes
- Stream modes.
- GET /collections/stream-actions
- Actions for money and safe pages (see below.)
- GET /collections/query-group-by
- Sales funnel breakdown columns.
- GET /collections/query-funnel-metrics
- Sales funnel computed metrics.
- GET /collections/query-log-columns
- Click log columns. :::

(stream-actions)=

Stream Actions

The following table details available actions for money and safe pages:

:::{list-table} :header-rows: 1

- Action
- Description
- local
- Local file ("zero redirect").
- proxy
- Reverse proxy.
- fetch
- Insert HTML code.
- iframe
- Display in iframe.
- 301
- HTTP 301 redirect.
- 302
- HTTP 302 redirect.
- 303
- HTTP 303 redirect.
- noop
- No action.
- refresh
- HTTP Refresh redirect.
- meta
- HTML meta refresh redirect.
- return
- Custom HTTP response code.
- php
- Execute PHP code.
- js
- Execute JavaScript code.
- xar
- X-Accel-Redirect header.
- xsf
- X-Sendfile header. :::

(streams)=

Managing Streams

A stream is represented as an object with the following properties:

:::{list-table} :header-rows: 1

- Property
- Type
- Description
- stream_id
- String
- Stream identifier.
- account_id
- String
- Account identifier. Read-only.
- name
- String
- Stream name.
- tags
- Array of strings
- Stream tags (up to 32.)
- mode
- String
- Mode, one of: Filter, Review, Money, or White.
- notes
- String
- Any notes you may want to write down.
- money_pages
- Array of objects
- Array of money pages, up to 254, each having the following properties:
  
  page -- URL / file path / code (depending on action), string
  action -- action to perform for the visitor, string
  arg_passthru -- whether to perform URL parameters passthru, boolean
  weight -- weight for rotation, integer
  enabled -- whether this money page is enabled, boolean
- rotator
- String
- Money page rotator, either Split or Timer.
- safe_pages
- Array of exactly one object
- Safe page. Array of exactly one object with the following properties:
  
  page -- URL / file path / code (depending on action), string
  action -- action to perform for the visitor, string
  arg_passthru -- whether to perform URL parameters passthru, boolean
- filter_level
- Integer or string
- Filtering level, one of:
  0 or Off
  1 or Low
  2 or Medium
  3 or High
  4 or Paranoid
- enable_fp
- Boolean
- Enable JavaScript fingerprinting and VLA™ model training.
- enable_ua
- Boolean
- Enable built-in user agent-based filters.
- require_unique
- Boolean
- Allow only unique visitors.
- require_touch
- Boolean
- Require touchscreen support (needs JS fingerprinting.)
- allow_apps
- Boolean
- Allow traffic from mobile apps.
- allow_embed
- Boolean
- Allow traffic from frames, iframes, and embedded objects.
- countries
- Array of strings
- Allowed country codes in two-letter format.
- os
- Array of strings
- Allowed operating systems.
- browsers
- Array of strings
- Allowed browsers.
- engines
- Array of strings
- Allowed browser engines.
- languages
- Array of strings
- Allowed browser language codes.
- timezones
- Array of integers
- Allowed time zones as integer hour offsets from UTC.
- tz_match_ip
- Boolean
- Match browser time zone with IP address time zone.
- skipClicks
- Integer
- Number of first clicks to block (delayed start.)
- skip_clicks_mode
- String
- Skip clicks mode, one of:
  
  all -- decrease the skip clicks counter for all clicks
  money -- decrease the counter only for legitimate visitors
  safe -- decrease the counter only for bots, moderators, etc
- ip_list_mode
- String
- IP/ASN list mode, one of:
  
  black -- block IP addresses/ASN in the blacklist except those in the whitelist
  white -- block IP addresses/ASN in the blacklist or not in the whitelist
  special -- block IP addresses/ASN in the blacklist, allow IP addresses/ASN in the whitelist
- ip_on_review
- Boolean
- Blacklist all IP addresses in Review mode.
- extrapolate_ipv4
- Integer between 0 and 255
- IPv4 extrapolation.
- extrapolate_ipv6
- Integer between 0 and 64
- IPv6 extrapolation.
- cost_parameter
- String
- Click cost parameter name.
- sid_parameter
- String
- Sub ID parameter name.
- cid_parameter
- String
- Click ID parameter name.
- url_rules
- Array of objects
- URL rules. See URL rule object structure description.
- schedule
- Array of objects
- Schedule (dayparting.) See Schedule rule object structure description.
- ua_list_mode
- String
- User agent list mode, one of:
  
  black -- block user agents in the blacklist except those in the whitelist
  white -- block user agents in the blacklist or not in the whitelist
  special -- block user agents in the blacklist, allow user agents in the whitelist
- ua_blacklist
- String or array of strings
- User agent blacklist.
- ua_whitelist
- String or array of strings
- User agent whitelist.
- referer_regex
- String
- Regular expression for filtering by referrer. :::

Example:

{
  "stream_id": "1eacc6d0-875f-6f5c-bff8-00162501c2b4",
  "account_id": "1eaa2ce5-d4dd-63ec-b8a4-00162501c2b4",
  "name": "Example Stream",
  "tags": ["Tag1", "Tag2"],
  "mode": "Filter",
  "notes": "This is an example comment.",
  "money_pages": [
    {
      "page": "https://example.com/offer1?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 10,
      "enabled": true
    },
    {
      "page": "https://example.com/offer2?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 20,
      "enabled": true
    }
  ],
  "rotator": "Split",
  "safe_pages": [
    {
      "page": "safe.html",
      "action": "local",
      "arg_passthru": true
    }
  ],
  "filter_level": "High",
  "enable_fp": true,
  "enable_ua": true,
  "require_unique": true,
  "require_touch": false,
  "allow_apps": false,
  "allow_apps": true,
  "countries": ["AE", "HK"],
  "os": ["iOS", "macOS"],
  "browsers": ["Google Chrome"],
  "engines": ["Blink"],
  "languages": ["en", "fr", "es"],
  "timezones": [-5, -6, -7],
  "tz_match_ip": true,
  "ip_on_review": true,
  "cost_parameter": "cost",
  "sid_parameter": "zoneid",
  "cid_parameter": "clickid",
  "url_rules": [
    {
      "param": "zoneid",
      "op": "REGEX",
      "arg": "[[:alnum:]-_]{8,}",
      "enabled": true
    }
  ],
  "schedule": [
    {
      "days": ["Sun", "Sat"],
      "since": "15:30:00",
      "till": "22:15:00"
    }
  ]
}

URL Rule Object

An URL rule object has the following structure:

{
  "param": "gclid",
  "op": "REGEX",
  "arg": "[[:alnum:]-_]{55,}",
  "enabled": true
}

:::{list-table} URL Rule Properties :header-rows: 1

- Property
- Type
- Description
- param
- String
- Name of the URL parameter that this rule operates on.
- op
- String
- Rule operator. See the operator table below for details.
- arg
- String
- Operator argument. See the operator table below for details.
- enabled
- Boolean
- Rule is enabled flag. :::

:::{list-table} URL Rule Operators :header-rows: 1

- Operator
- Argument
- Description
- ASSIGN
- Optional
- Sets parameter to the value supplied in the rule argument.
- RENAME
- Optional
- Renames parameter to the name supplied in the rule argument.
- DELETE
- Ignored
- Deletes parameter.
- EXISTS
- Ignored
- Checks that parameter exists.
- NEXISTS
- Ignored
- Checks that parameter does not exist.
- REGEX
- Optional
- Checks that parameter value matches regular expression supplied in the rule argument.
- IREGEX
- Optional
- Checks that parameter value matches regular expression supplied in the rule argument (case-sensitive).
- NREGEX
- Optional
- Checks that parameter value does not match regular expression supplied in the rule argument.
- NIREGEX
- Optional
- Checks that parameter value does not match regular expression supplied in the rule argument (case-insensitive).
- EQ
- Optional
- Checks that parameter value equals the rule argument.
- NEQ
- Optional
- Checks that parameter value does not equal the rule argument.
- GT
- Optional
- Checks that parameter value is greater than the rule argument.
- GE
- Optional
- Checks that parameter value is greater than or equal to the rule argument.
- LT
- Optional
- Checks that parameter value is less than the rule argument.
- LE
- Optional
- Checks that parameter value is less than or equal to the rule argument. :::

Schedule Rule Object

A schedule (dayparting) rule object has the following structure:

{
  "days": ["Sun", "Sat"],
  "since": "15:30:00",
  "till": "22:15:00"
}

:::{list-table} Schedule Rule Properties :header-rows: 1

- Property
- Type
- Description
- days
- Array of strings
- Days of week the rule applies to. Day is one of:
  
  Sun -- Sunday
  Mon -- Monday
  Tue -- Tuesday
  Wed -- Wednesday
  Thu -- Thursday
  Fri -- Friday
  Sat -- Saturday
- since
- String
- Allow visitors since time of day in HH:MM:SS format, e.g. 15:30:00.
- till
- String
- Allow visitors till time of day in HH:MM:SS format, e.g. 22:15:00. :::

List Streams

GET /streams

This endpoint returns a list of streams configured in the account. The list is paginated and ordered by stream name in ascending lexicographic order.

Supported URL parameters:

:::{list-table} :header-rows: 1

- Parameter
- Type
- Default Value
- Description
- page
- Integer
- 1
- Number of page to display.
- per-page
- Integer, from 1 to 100
- 20
- Number of streams per page.
- name
- Integer
- None
- Output only streams whose names contain the specified substring (case-insensitive.) :::

Stream List Metadata

HEAD /streams

This endpoint returns several headers with useful pagination information:

:::{list-table} :header-rows: 1

- Header
- Type
- Description
- X-Pagination-Total-Count
- Integer
- Total number of streams.
- X-Pagination-Page-Count
- Integer
- Total number of pages. :::

Supported URL parameters:

:::{list-table} :header-rows: 1

- Parameter
- Type
- Default Value
- Description
- per-page
- Integer, from 1 to 100
- 20
- Number of queries per page. :::

Get Stream

GET /streams/<ID>

This endpoint returns the stream specified by <ID>.

Create Stream

POST /streams

This endpoint creates and returns a new stream. Send a stream object in request body. All stream object properties have default values, so you need to specify only those properties that you want to assign concrete values to, e.g. {"name":"My Stream"}.

Update Stream

PATCH /streams/<ID>

This endpoint updates the stream specified by <ID>. Send a stream object in request body. You need to specify only those properties that you want to change; the rest of them will be left unchanged.

Copy Stream

COPY /streams/<ID>

This endpoint copies the stream specified by <ID>. Optionally you may send a stream object in request body--its properties will overwrite properties in the copy, saving you an extra PATCH call.

Delete Stream

DELETE /streams/<ID>

This endpoint deletes the stream specified by <ID>.

(integration)=

Integration PHP Files

You may download index.php, filter.php, and ajax.php files for any stream via the following requests:

:::{list-table} :header-rows: 1

- File
- Endpoint
- index.php and filter.php
- GET https://clients.adspect.ai/getindex.php?sid=<ID>
  Replace <ID> with an actual Adspect stream ID.
- ajax.php
- GET https://clients.adspect.ai/getindex.php?sid=<ID>&mode=ajax
  Replace <ID> with an actual Adspect stream ID. :::

Guest Access to Reporting

Guest access to reporting lets third parties view pre-defined portions of your statistics without having to log into the system. Guess access management is centered around saved report queries:

You create a saved query that specifies allowed report parameters (dates and filters);
The API returns an ID of the saved query;
A guest may then execute this query in the Reporting section by entering the saved query ID in the corresponding field, or by navigating to a link like https://clients.adspect.ai/reporting?query_id=<ID>, where <ID> should be replaced with the saved query ID.

:::{note} At most 100 saved queries may be created. :::

Saved query is represented by an object with the following properties:

:::{list-table} :header-rows: 1

- Property
- Type
- Description
- query_id
- String
- Saved query ID. Read-only.
- owner_id
- String
- Saved query owner's account ID. Read-only.
- date_from
- Integer or string
- Minimum Unix timestamp since which the report will be pulled.
- date_to
- Integer or string
- Maximum Unix timestamp until which the report will be pulled.
- time_zone
- String
- Default time zone for displaying date and time.
- group_by
- Array of strings
- Default sales funnel breakdown.
- stream_id
- Array of strings
- Filter by stream IDs.
- ip_address
- Array of strings
- Filter by IP addresses.
- asn
- Array of integers or strings
- Filter by autonomous system numbers (ASN). ASNs may be specified as strings, e.g. AS65536 or AS1.10.
- country_code
- Array of strings
- Filter by country codes in two-letter format.
- os
- Array of strings
- Filter by operating systems.
- browser
- Array of strings
- Filter by browsers.
- engine
- Array of strings
- Filter by browser engines.
- sub_id
- Array of strings
- Filter by sub IDs.
- click_id
- Array of strings
- Filter by click IDs.
- mode
- Array of strings
- Filter by stream modes.
- target
- Array of integers
- Filter by displayed page:
  
  0 -- safe page
  1--255 -- money page with the corresponding ordinal number :::

All properties are optional. If a particular property is not needed, then you may either omit it or set it to null (or an empty array [] where array values are expected.)

Example:

{
  "query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb",
  "owner_id": "1eb5991f-a25b-68f4-b171-00162501c2b4",
  "date_from": 1577836800,
  "date_to": null,
  "time_zone": "Asia/Dubai",
  "group_by": [],
  "stream_id": ["6792f6ce-f153-439f-b223-f58749f1210f"],
  "ip_address": [],
  "asn": [],
  "country_code": ["HK", "AE"],
  "os": ["iOS", "macOS"],
  "browser": ["Apple Safari"],
  "engine": [],
  "sub_id": [],
  "click_id": [],
  "mode": ["Filter"],
  "target": []
}

Query List

GET /reports

This endpoint returns a paginated list of created saved queries in the account.

Supported URL parameters:

:::{list-table} :header-rows: 1

- Parameter
- Type
- Default Value
- Description
- page
- Integer
- 1
- Number of page to display.
- per-page
- Integer, from 1 to 100
- 20
- Number of queries per page. :::

Query List Metadata

HEAD /reports

This endpoint returns several headers with useful pagination information:

:::{list-table} :header-rows: 1

- Header
- Type
- Description
- X-Pagination-Total-Count
- Integer
- Total number of queries.
- X-Pagination-Page-Count
- Integer
- Total number of pages. :::

Supported URL parameters:

:::{list-table} :header-rows: 1

- Parameter
- Type
- Default Value
- Description
- per-page
- Integer, from 1 to 100
- 20
- Number of queries per page. :::

Get Query

GET /reports/<ID>

This endpoint returns the query specified by <ID>.

Create Query

POST /reports

This endpoint creates and returns a new query. Send a query object in request body.

Update Query

PATCH /reports/<ID>

This endpoint updates the query specified by <ID>. Send a query object in request body. You need to specify only those properties that you want to assign values to; the rest of the properties will remain unchanged.

Copy Query

COPY /reports/<ID>

This endpoint copies the query specified by <ID>. Optionally you may send a query object in request body--its properties will overwrite properties in the copy, saving you an extra PATCH call.

Delete Query

DELETE /reports/<ID>

This endpoint deletes the query specified by <ID>.

Reporting API

Adspect Reporting API provides programmatic access to Adspect statistics via two endpoints:

Sales funnel endpoint for creating aggregated reports;
Click log endpoint for extracting raw click by click data.

These endpoints functionally mirror the Reporting section of the Adspect clients area.

Reporting Filters

Both endpoints support filters via URL parameters to narrow down the portion of statistics data to be processed, e.g:

date_from=1672520400&date_to=1675198800&country_code[]=AE&os[]=iOS&os[]=macOS

A report made with such filters will only contain clicks and conversions that match all of the following conditions:

during January 2023: date_from=1672520400&date_to=1675198800
from United Arab Emirates: country_code[]=AE
from iOS or macOS devices: os[]=iOS&os[]=macOS

:::{tip} You may specify dates and times as human-readable strings instead of Unix timestamps, e.g. 1 Jan 2023 or 2023-01-01 instead of 1672520400. Adspect will do its best to parse such a date string in a meaningful way. :::

The following table lists available report filters. All parameters are optional.

:::{note} Parameters ending with [] are arrays: you may specify several such parameters, and their values will be added together into a logical OR condition, e.g. os[]=iOS&os[]=macOS will extract clicks and conversions that came from iOS or macOS devices. :::

:::{list-table} :header-rows: 1

- Parameter
- Type
- Description
- query_id
- String
- Saved query ID for guest access to reports of other Adspect users.
- date_from
- Integer or string
- Minimum Unix timestamp since which the report will be pulled.
- date_to
- Integer or string
- Maximum Unix timestamp until which the report will be pulled.
- time_zone
- String
- Time zone for displaying date and time, e.g. Asia/Dubai.
- stream_id[]
- String
- Filter by stream IDs.
- ip_address[]
- String
- Filter by IP addresses.
- asn[]
- Integer or string
- Filter by autonomous system numbers (ASN). ASNs may be specified as strings, e.g. AS65536 or AS1.10.
- country_code[]
- String
- Filter by country codes in two-letter format.
- os[]
- String
- Filter by operating systems.
- browser[]
- String
- Filter by browsers.
- engine[]
- String
- Filter by browser engines.
- sub_id[]
- String
- Filter by sub IDs.
- click_id[]
- String
- Filter by click IDs.
- mode[]
- String
- Filter by stream modes.
- target[]
- Integer
- Filter by displayed page:
  
  0 -- safe page
  1--255 -- money page with the corresponding ordinal number :::

(reporting-sales-funnel)=

Sales Funnel

GET /reports/funnel

This endpoint returns an aggregated report in JSON array per row format. The order of array elements corresponds to the order of the group_by[] parameters followed by the order of the metrics[] parameters.

The following table lists URL parameters specific to the sales funnel endpoint.

:::{note} Parameters ending with [] are arrays: you may specify several such parameters, and their values will be added together, e.g. group_by[]=date&group_by[]=stream_id will result in funnel breakdown first by date and then by stream IDs.

Likewise, metrics[]=clicks&metrics[]=money_hits will add clicks and money hits metrics to the output, in that order. :::

:::{list-table} :header-rows: 1

- Parameter
- Type
- Description
- group_by[]
- String, optional
- Add a sales funnel breakdown column to the output.
- metrics[]
- String, required
- Add a sales funnel metric column to the output. :::

(reporting-sales-funnel-breakdown)=

Sales Funnel Breakdown Columns

The following table lists available breakdown columns for the group_by[] URL parameter.

:::{list-table} :header-rows: 1

- Column
- Description
- date
- Date in YYYY-MM-DD format.
- month
- Month in YYYY-MM format.
- stream_id
- Stream ID.
- asn
- Autonomous system number (ASN).
- country_code
- Country code in two-letter format.
- os
- Operating system.
- browser
- Browser.
- engine
- Browser engine.
- language
- Browser language.
- sub_id
- Sub ID.
- mode
- Stream mode at the moment of the click.
- target
- Displayed page:
  
  0 -- safe page
  1--255 -- money page with the corresponding ordinal number
- tag
- Mnemonic tag representing a particular block reason. :::

:::{tip} This list may also be obtained via the GET /collections/query-group-by collection endpoint. :::

(reporting-sales-funnel-metrics)=

Sales Funnel Metrics

The following table lists available sales funnel metrics for the metrics[] URL parameter.

:::{important} Please specify only those metrics that you actually need in your API requests. :::

:::{list-table} :header-rows: 1

- Metric
- Description
- clicks
- Total number of clicks.
- uniques
- Approximate number of unique visitors as per uniqueness of their IP addresses.
- fingerprints
- Number of visitors that successfully produced a JavaScript fingerprint. This figure may be less than the total number of clicks for various reasons, most often due to inability of dumb bots to run JavaScript code.
- money_hits
- Number of visitors that have been shown the money page.
- money_uniques
- Number of unique visitors that have been shown the money page.
- safe_hits
- Number of visitors that have been shown the safe page.
- givt
- General invalid traffic, that is, the number of visitors blocked by superficial filters such as IP address blacklists, user agent matching, targeting, day parting (schedule), etc.
- sivt
- Sophisticated invalid traffic, that is, the number of browser fingerprints that Adspect consciously filtered out as bad traffic.
- mia
- Clicks missing in action, the figure = the number of visitors that failed to produce or submit a browser fingerprint. As mentioned above, these are often dumb bots with missing JavaScript support. Another common reason is network latency, especially evident in traffic with slow connection rates, e.g. 3G/EDGE, when visitors manage to close the tab or window before their fingerprint is submitted.
- quality
- Percentage of money hits in the whole click volume. This is the best metric for evaluating traffic quality as a whole and may be used to compare different traffic sources, publishers, ad spots, etc. Especially useful with grouping by sub ID for compiling blacklists of bot-ridden zones, as described in the dedicated paragraph.
- expenses
- Total traffic cost computed as a sum of costs of each click, if passed in a click URL parameter.
- conversions
- Total number of conversions.
- cr
- Conversion rate = conversions / clicks.
- revenue
- Total revenue computed as a sum of payouts of each conversion, if passed in postback.
- profit
- Net profit = revenue − cost.
- roi
- Return on investment = profit / cost.
- cpc
- Cost per click = cost / clicks.
- cpm
- Cost per mille (thousand clicks) = cost / clicks × 1000.
- cpa
- Cost per action = cost / conversions.
- epl
- Earn per lead = revenue / conversions.
- ecpc
- Effective cost per click = revenue / clicks.
- ecpm
- Effective cost per mille (thousand clicks) = revenue / clicks × 1000. :::

:::{tip} This list may also be obtained via the GET /collections/query-funnel-metrics collection endpoint. :::

(reporting-sales-funnel-examples)=

Examples

Example #1: obtaining basic metrics for all streams, grouped by stream ID:

GET /reports/funnel?group_by[]=stream_id&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality

["1ec5880e-bcb6-49b8-9778-a31d22b70708", "1453", "754", "699", 0.5189263592567103]
["07ac03df-268e-41ff-84ba-adfe2241beb2", "3219", "2034", "1125", 0.6318732525629077]
["7a3d39f7-fe75-431e-8be6-9ea9b56b1e4a", "179", "0", "179", 0]
["9f79b75f-20ef-4654-8141-b8bbb2124ec4", "65", "0", "65", 0]

Example #2: obtaining per-day basic metrics for the stream with ID 07ac03df-268e-41ff-84ba-adfe2241beb2:

GET /reports/funnel?group_by[]=date&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2

["2024-04-01", "931", "343", "582", 0.3684210526315789]
["2024-04-02", "1166", "829", "300", 0.7109777015437393]
["2024-04-03", "1113", "855", "243", 0.7681940700808625]
["2024-04-04", "9", "7", "0", 0.7777777777777778]

(reporting-click-log)=

Click Log

GET /reports/log

This endpoint returns a portion of the raw click log in JSON array per row format. The order of array elements corresponds to the order of the columns[] parameters.

The following table lists URL parameters specific to the click log endpoint.

:::{note} Parameters ending with [] are arrays: you may specify several such parameters, and their values will be added together, e.g. columns[]=timestamp&columns[]=ip_address will add timestamp and IP address columns to the output, in that order. :::

:::{list-table} :header-rows: 1

- Parameter
- Type
- Description
- columns[]
- String, required
- Add a click log column to the output. :::

(reporting-click-log-columns)=

Click Log Columns

The following table lists available click log columns for the columns[] URL parameter.

:::{important} Please specify only those columns that you actually need in your API requests. :::

:::{list-table} :header-rows: 1

- Column
- Description
- timestamp
- Date and time of the click or conversion.
- ip_address
- IP address of the visitor.
- asn
- Autonomous system number of the visitor.
- account_id
- Account ID.
- stream_id
- Stream ID.
- country_code
- Country code in two-letter format.
- os
- Operating system.
- browser
- Browser.
- engine
- Browser engine.
- languages
- List of browser languages.
- cost
- Click cost or conversion payout.
- sub_id
- Sub ID.
- click_id
- Click ID.
- mode
- Stream mode at the moment of the click.
- sequence
- Click processing stage:
  
  0 -- basic check
  1 -- JavaScript fingerprint check
  255 -- conversion
- target
- Displayed page:
  
  0 -- safe page
  1--255 -- money page with the corresponding ordinal number
- tags
- List of mnemonic tags that represent particular filtering reasons. :::

:::{tip} This list may also be obtained via the GET /collections/query-log-columns collection endpoint. :::

(reporting-click-log-examples)=

Examples

Obtaining today's click log of the stream with ID 07ac03df-268e-41ff-84ba-adfe2241beb2:

GET /reports/log?columns[]=timestamp&columns[]=ip_address&columns[]=country_code&columns[]=target&date_from=today&date_to=tomorrow&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2

["2024-04-01 00:00:00", "23.83.90.68", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:30ff:8::33", "SE", 0]
["2024-04-01 00:00:00", "47.128.19.245", "SG", 0]
["2024-04-01 00:00:00", "176.223.109.119", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:20ff:76::33", "US", 0]
["2024-04-01 00:00:00", "89.248.163.208", "NL", 0]
["2024-04-01 00:00:00", "47.128.98.197", "SG", 0]
["2024-04-01 00:00:00", "47.128.25.161", "SG", 0]
["2024-04-01 00:00:00", "95.90.237.130", "DE", 0]
["2024-04-01 00:00:00", "176.5.15.114", "DE", 0]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

REST API

Authentication

Collections

Stream Actions

Managing Streams

URL Rule Object

Schedule Rule Object

List Streams

Stream List Metadata

Get Stream

Create Stream

Update Stream

Copy Stream

Delete Stream

Integration PHP Files

Guest Access to Reporting

Query List

Query List Metadata

Get Query

Create Query

Update Query

Copy Query

Delete Query

Reporting API

Reporting Filters

Sales Funnel

Sales Funnel Breakdown Columns

Sales Funnel Metrics

Examples

Click Log

Click Log Columns

Examples

Files

api.md

Latest commit

History

api.md

File metadata and controls

REST API

Authentication

Collections

Stream Actions

Managing Streams

URL Rule Object

Schedule Rule Object

List Streams

Stream List Metadata

Get Stream

Create Stream

Update Stream

Copy Stream

Delete Stream

Integration PHP Files

Guest Access to Reporting

Query List

Query List Metadata

Get Query

Create Query

Update Query

Copy Query

Delete Query

Reporting API

Reporting Filters

Sales Funnel

Sales Funnel Breakdown Columns

Sales Funnel Metrics

Examples

Click Log

Click Log Columns

Examples