Querying the API

This documentation is about an Early Adopter feature and the instructions detailled here are subject to changes. Please contact your usual AB Tasty contact if some instructions are unclear or if something is missing.

This page is a description of each object that structure the final payload. For a more guided version of the documentation, visit the walkthrough.

Sending the query

POST https://api-data-explorer.abtasty.com/v2/clients/{{account_identifier}}/query

Arguments

Parameter	Type	Required	Format	Description
account_identifier	string	true	Example: "37976"	Your account ID (or environmentId for server-side)

Headers

Name	Required	Value
Content-Type	true	application/json
Authorization	true	Bearer {{your_token}}
x-source	true (server-side only)	flagship

Building the payload

The payload must be inserted in the body of the request.

Example of payload:

{
    "timeIntervals": [
        {
            "start": "1640991600",
            "end": "1646290561"
        }
    ],
    "filters": {
        "single": {
            "field": "device",
            "operator": "EQUAL",
            "value": "Desktop"
        },
        "filteringStrategy": "PER_USER"
    },
    "dimensions": [
        "campaignId",
        "variationId"
    ],
    "metrics": [
        {
            "key": "users",
            "name": "",
            "filter": null,
            "type": "COMMON"
        },
        {
            "key": "npsCount",
            "name": "npsPromoters",
            "filter": {
                "single": {
                    "field": "npsScore",
                    "operator": "GREATER",
                    "value": "8"
                },
                "filteringStrategy": "PER_USER"
            },
            "type": "COMMON"
        }
    ],
    "orderBy": [
        {
            "field": "users",
            "direction": "DESC"
        }
    ],
    "limit": 100
}

Setting up the dates

You will need a timeframe for your query. Select the two epochs (timestamps but in seconds) that will bound your request.

"timeIntervals": [
    {
        "start": "1640991600",
        "end": "1646290561"
    }
]

Remember that the larger the window, the longer it will take for our engine to process it or the biggest part of your fair-use it will consume.

Choosing your dimensions

Choose which dimensions you want to get in the answer.

dimensions": [
      "campaignId",
      "variationId"
  ]

It must be a array of dimensions. Dimensions are enumerative values that are being collected by our tool, automatically or through specific parameters you have set up. Examples: campaignId, device name, event action, transaction revenue, etc…

The list of dimensions can be found here.

Choosing your metrics

Choose which metrics you want to get in the answer.

"metrics": [        
  {
      "key": "users",
      "name": "users",
      "filter": null,
      "type": "COMMON"
  },
  {
      "key": "sessions",
      "name": "sessions",
      "filter": null,
      "type": "COMMON"
  }
]

It must be a tab of objects, one object per metric. Metrics are counters that will be computed and filtered out depending on the dimensions you chose. For example, if you want to get the amount of UVs per browser, you will put “users” as a metric and “browser name” as a dimension.

key is the exact name of the metric.

The list of metrics can be found here.

name is optional (can be replaced by an empty String) and will only affect the result. It is used to give a custom name to a metric.

filter is optional and used to filter the metric, can be set to null

type must be set to “COMMON”

Ordering the result

You can simply add an order instruction for the result.

"orderBy": [
    {
        "field": "users",
        "direction": "DESC"
    }
]

This won’t affect the content of the result.

field must be the exact name of the metric.

direction can either be DESC or ASC

Limiting the result

You can add a limit to the number of lines that will be returned.

  "limit": 100

This will not change the amount of data that will be parsed!

Filters

There are three levels of filters:

• selecting the population you will be using for this request,

• filtering the metrics you will be receiving,

• filtering on campaign history

Selecting your population

The first level of filter you will want to set in the population you will get data from. This allows you to narrow your request to remove all the unnecessary population.

Examples of populations you want to filter on:

Only the visitors that have seen campaign #362412

Only the visitors that have sent an “Add to cart” EVENT

This is achieved by adding a root filters argument in the payload. For example:

{
    "timeIntervals": [
        {
            "start": "1657707046",
            "end": "1658916646"
        }
    ],
    "filters": {
        "single": {
            "field": "campaignId",
            "value": "871873"
        },
        "filteringStrategy": "PER_SESSION"
    },
    "dimensions": [
        "date"
    ],
    "metrics": [
        {
            "key": "users",
            "name": "users",
            "type":"COMMON"
        },
        {
            "key": "uniqueEvents",
            "name": "uniqueEvents",
            "type": "COMMON"
        }
    ],
    "limit": 100
}

Single filter condition

When the population is only filtered on one condition, the syntax is pretty simple:

"filters": {
    "single": {
        "field": "campaignId",
        "value": "871873"
    },
    "filteringStrategy": "PER_SESSION"
}

In this example, the population will be filtered on the campaign ID. All the visitors that haven’t been exposed to campaign #871873 won’t be parsed.

The field argument is selecting the dimension and the value argument the expected value. By default, the request will be made on an EQUAL match, but you can add an operator parameter to change that.

Possible values are:

• EQUAL

• NOT_EQUAL

• GREATER

• GREATER_OR_EQUAL

• LESS

• LESS_OR_EQUAL

• CONTAINS

• NOT_CONTAINS

• REGEXP

• IS_NULL

• IS_NOT_NULL

The filteringStrategy argument is used to decide if the population must validate the criterion at the session level or user-wide.

The two possible values are PER_SESSION or PER_USER.

For example, if one visitor has made two visits but only one transaction (let's say on visit #2), getting the metric sessions with a filter on the transaction will return 2 with the PER_USER value and only 1 with PER_SESSION.

Excluding filter condition

The same logic as above applies but with a global exclusion. Only the keyword needs to be changed:

"excludeFilters": {
    "single": {
        "field": "campaignId",
        "value": "871873"
    },
    "filteringStrategy": "PER_SESSION"
}

In this example, the population will be excluded based on the campaign ID. All the visitors that have been exposed to campaign #871873 won't be selected.

Multiple filters condition

You can add multiple filters and combine them. You will achieve that by adding a “composite” filter.

"filters": {
    "composite": {
        "singleHitCondition":true,
        "operator": "OR",
        "filters": [
            {
                "single": {
                    "field": "campaignId",
                    "operator": "EQUAL",
                    "value": "885397"
                },
                "filteringStrategy": "PER_USER"
            },
            {
                "single": {
                    "field": "campaignId",
                    "operator": "EQUAL",
                    "value": "883918"
                },
                "filteringStrategy": "PER_USER"
            }
        ]
    }
}

In this example, the population will be also filtered on the campaign ID. However, this time, we want to have visitors that have seen campaign #885397 OR campaign #883918.

The composite filter is composed of two single filters (exclusion is possible).

The singleHitCondition is set to true, which means that the two filters will be matched on the same hit. When evaluating the filter on the specific arguments of different type of hits (for example a transaction revenue and an event action), this parameter must be set to false as the condition would be impossible if set to true.

This syntax would also work:

"filters": {
    "single": {
        "field": "campaignId",
        "operator": "REGEX",
        "value": "(^885397$)|(^883918$)"
    },
    "filteringStrategy": "PER_USER"
}

Nested filters

It is possible to nest another composite filter inside a composite filter. For example:

"filters": {
  // root composite
  "composite": {
    "singleHitCondition": true,
    "filters": [
      {
        "single": {
          "field": "device",
          "operator": "EQUAL",
          "value": "Mobile"
        }
      },
      {
        // nested composite
        "composite": {
          "singleHitCondition": false,
          "filters": [
            {
              "single": {
                "field": "browser",
                "operator": "EQUAL",
                "value": "Chrome"
              }
            },
            {
              "single": {
                "field": "country",
                "operator": "NOT_EQUAL",
                "value": "Spain"
              }
            }
          ]
        }
      }
    ]
  }
}

Refining your metrics

After you selected your population, you can add a filter directly to your metrics.

{
    "timeIntervals": [
        {
            "start": "1657707046",
            "end": "1658916646"
        }
    ],
    "filters": {
        "single": {
            "field": "eventAction",
            "value": "Click productss"
        },
        "filteringStrategy": "PER_USER"
    },
    "metrics": [
        {
            "key": "transactions",
            "name": "transactions",
            "type": "COMMON",
            "filter":{
                "single": {
                    "field":"affiliation",
                    "operator":"EQUAL",
                    "value":"Purchase"
                }
            }
        }
    ],
    "limit": 100
}

In this example, we select all the visitors that have sent a “Click products” EVENT and want to have the number of transactions but only for the affiliation (transaction goal name) “Purchase”. Not adding the filter would have displayed the number of transactions for all existing transaction goals.

The syntax is the same as for a population filter. However, the field you are filtering on must be relative to the metric this filter is nested on.

Filtering on campaign history

As exposed in the data schema documentation, the campaign history determines if a hit has been done after being exposed to a specific campaign. You might want to only get data from hits that happen after a visitor has been exposed to a campaign.

For this, you would use the campaignFilter parameter. The syntax is exactly the same as the filters but it will only return hits that has the specified campaignId in the campaign history.

The main difference is that a filters parameter would always return if a transaction has been made during the visitor's session while campaignFilter will only return this transaction IF the visitor has seen the campaign before.

"campaignFilter": {
    "single": {
        "field": "campaignId",
        "value": "871873"
    }
}

Examples library

In this section you will find several examples with their description.

---

Getting the amount of users / sessions / transactions grouped by browser and browser version for all visitors that have seen at least one URL that contains the keyword “/how” in the time range.

{
    "timeIntervals": [
        {
            "start": "1667059200",
            "end": "1667980740"
        }
    ],
    "filters": {
        "single": {
            "field": "url",
            "operator": "CONTAINS",
            "value": "/how"
        }
    },
    "dimensions": [
        "browser",
        "browserVersion"
    ],
    "metrics": [
        {
            "key": "users"
        },
        {
            "key": "sessions"
        },
        {
            "key": "transactions"
        }
    ],
    "limit": 100
}