💡 If you are in the process of ditching the spreadsheets or already have a proper analytics system, you can use our API to fetch the data you need automatically, without having to import a CSV file every now and again.
💡 Bear in mind that our API supports the GET method only. It means that you won't be able to delete or add domains or ad formats using the API.
Getting an API token
Rate Limit is 1200 requests per minute, per user. Each API response is also cached for 60 seconds.
To get an API token, go to the Settings (API tab) page from the left-hand menu and click Generate new token:
❗️ Please note that the token can only be viewed and copied at the time of generation. After that, it will no longer be accessible.
On the API page, you can also see:
The number of active tokens you currently have — you can have up to 5 active API tokens at a time;
A clickable link to the API documentation;
Information about all your active tokens, including:
Name
Status
Expiration date (each token will be active for 1 year)
Creation date
Date and time of last use
IP address
Country
An option to rename or delete each individual token:
You will receive an email notification whenever one of your tokens is close to expiring.
Include the token in a header parameter called X-API-Key:
Available endpoints and URI
All requests are made to the following URI:
<https://api3.adsterratools.com/publisher>
Below you will find the list of available endpoints:
/domains/{format}— returns the websites you've added to Adsterra, including their names and unique IDs;/domain/{domain_id}/placements.{format}— your placements on the specified domain; note that you'll need the domain_id retrieved via the/domains/{format}request first;/placements.{format}— returns the full list of your placements;/smart-links.{format}— returns the full list of your Smartlinks;/stats.{format}— a report comprising impressions, clicks, CTR, CPM, and revenue by date; you can specify domain_id, placement_id, start and finish dates, as well as a specific GEO.
The data can be retrieved as JSON, XML, and CSV. Make sure to specify the data format you need in the URI:
<https://api3.adsterratools.com/publisher/domains.json>
Example requests on how to get Adsterra statistics via API
We'll walk you through a few requests using Postman — a popular API testing tool. You can use it to get the idea of how we format the data and to test the requests you are planning to make.
First, we need to get the IDs of our domains from the following URI:
<https://api3.adsterratools.com/publisher/domains.json>
In the response body, we can see the following:
Let's find placement_id's from the first website (domain_id 1385226):
Now, we can use domain_id and placement_id to fetch this placement's stats:
The response:
Possible errors and ways to fix them
401 — the token is incorrect. Please use the token available in your dashboard.
403 — the token is no longer valid. Please generate a new token.
404 — not found. Make sure the URI is correct.