Help centerWeb SDKMobile SDKREST API

API Overview

Suggest Edits

📘

API URL change

Smartlook has added data storage region that must be reflected in the REST API URL. By default, all projects are set to the EU region. To see what region you have set, go to the Organization tab and then Project settings. To discuss changing your data storage region, contact Smartlook Support.

Smartlook provides a set of useful methods to programmatically retrieve information about various resources. You can use the API to further analyze your user data and do a deeper exploration of values collected by Smartlook.

Resources

This API provides access to a number of resources available in Smartlook. The currently available resources are:

  • Visitors
  • Events
  • Funnels
  • Sessions

Using the API

Requests to the API are performed using the HTTP protocol to the host https://api.<REGION>.smartlook.cloud.
To access your project data, you have to get an API token that will be sent together with your request to authenticate it.
Your request to the API then must contain an authorization header as follows:

Authorization: Bearer <token>

For example, to list the events of your project, you perform the following call:

curl -X GET \\
  https://api.eu.smartlook.cloud/api/v1/events \\
  -H 'authorization: Bearer <token>' \\
  -H 'cache-control: no-cache'

The complete list of available endpoints is listed in the API reference. Each endpoint is prefixed by a version number (eg. /api/v1/events), however, specifying the version is not required.

To make things easier for you we prepared a Javascript client that can be used both in the browser and the Node.js.

Traversing paged results

When making an API requests to a resource that returns multiple objects, the result will be split into multiple pages.
All the paginated responses are using cursor-based pagination and therefore calls to pages are stable.
The response of paginated results has a pagination property, that contains two values - before and after.
These values point to the beginning and the end of the returned page respectively.

🚧

Don't store cursors

Cursors are only temporal values as they quickly may become invalid.

To get the link to the next page add after cursor to the query (?after=<after>) (for the previous page use the before the cursor).
There can be only one cursor in the query.
Links to both previous and next page can be found in the _links section of the response.
To get consistent results we recommend using _links for navigation between pages.

To change the number of results returned in response you may pass the limit parameter in the query.
This value will be then propagated to the _links in further responses or it will be set to a default value.

The response may then looks as follows:

{
    ...data,
    "pagination": {
        "before": "MTaxX34=",
        "after": "HellOW0rLD",
    }
    "_links": {
        "nextPage": "/api/events?after=HellOW0rLD&limit=10",
        "previousPage": "/api/events?before=MTaxX34=&limit=10"
    }
}

Managing API tokens

The Smartlook REST API uses tokens for authentication. You will need one if you are about to access the Smartlook REST API or you are integrating some of the third party applications with Smartlook.

You can manage your tokens in the settings of your project. To obtain a token, navigate in the Smartlook to your Account settings, and there select a project you want to access through the REST API.
On the right side, there is a section REST API where you can see the list of active tokens in your project. Next to each token, there is a time since the token was last used. Keep in mind, that when the token is inactive for more than 90 days, it will automatically become invalid.

📘

About managing tokens...

The tokens can be managed only by the owner of the project. If you want to access the REST API of projects you were invited in, please contact the owner to give you the token.

Creating API tokens

To create an API token:

  1. Go to your Project settings and click REST API.
REST API
  1. On the REST API page, click + New token.
  2. Enter a Token label.
  3. Click Save.
Token created

You successfully created an API token. You can copy the token and enter it where you need. The token is created in the scope of a single project. You have to create separate tokens for each project.
To help you manage the access to your projects in a more granular manner, you may create multiple tokens per a single project where each is for a different purpose.

🚧

Be careful!

Anyone with the token can access the data of your project. Please store the token securely and don't allow unauthorized entities to access it.
If you want to delete the token, you can do so in the Active tokens list.

Request limits

To keep our API available to as many people as possible, Smartlook has rate limits on the number of requests you can during a set period of time.

Request limits:

  • Free plan—Twenty (20) requests per hour
  • Paid plans—One hundred (100) requests per hour
  • REST API add-on—One thousand (1,000) requests per hour

To get information about your usage of the Smartlook REST API, call the /api/statistics endpoint. If you need to raise your request limit, contact the Smartlook support.

📘

Issues and bugs

Issues and bugs can be reported in the Smartlook REST API issue tracker.

Updated 6 months ago