Overview
The ROAS Evolution endpoint provides detailed analytics about Return on Advertising Spend (ROAS) over time. This endpoint allows you to track and analyze the effectiveness of your marketing investments across different channels and campaigns.
Endpoint Details
- Method: GET
- Authentication: Bearer Token required
Request Parameters
Headers
Header | Value | Required |
Authorization | Bearer {your_access_token} | Yes |
Accept | application/json | Yes |
Connection | keep-alive | Recommended |
Accept-Encoding | gzip, deflate, br | Recommended |
Query Parameters
Parameter | Type | Required | Description |
account_id | string | Yes | Your account identifier |
date_range | string | Yes | Date range for the data (format: YYYYMMDD,YYYYMMDD or predefined values like `this_month`) |
skip | integer | No | Number of records to skip (for pagination), defaults to 0 |
limit | integer | No | Maximum number of records to return, defaults to 100 with max value of 100 |
time_unit | string | No | Time unit for data aggregation: "daily", "weekly", or "monthly" (default: "daily") |
utm_medium | string | No | Filter by medium (e.g., seo, cpc) |
utm_source | string | No | Filter by source (e.g., google, newsletter) |
utm_campaign | string | No | Filter by campaign name |
country | string | No | ISO 3166-1 alpha-2 country code filter (e.g., "es" for Spain |
Example Request
cURL
```bash
curl --location 'https://app.sealmetrics.com/api/report/roas-evolution?account_id=000000000000000000001234&date_range=this_month&skip=0&limit=100&time_unit=daily' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI:ImpoaS1Nzg5MzQzIn0...' \
--header 'Accept: application/json' \
--header 'Connection: keep-alive' \
--header 'Accept-Encoding: gzip, deflate, br'
```
Python
```python
import requests
querystring = {
"account_id": "000000000000000000001234",
"date_range": "this_month",
"skip": "0",
"limit": "100",
"time_unit": "daily"
}
headers = {
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI:ImpoaS1Nzg5MzQzIn0...",
"Accept": "application/json",
"Connection": "keep-alive",
"Accept-Encoding": "gzip, deflate, br"
}
response = requests.request("GET", url, headers=headers, params=querystring)
print(response.text)
```
JavaScript
```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI:ImpoaS1Nzg5MzQzIn0...");
myHeaders.append("Accept", "application/json");
myHeaders.append("Connection", "keep-alive");
myHeaders.append("Accept-Encoding", "gzip, deflate, br");
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch("https://app.sealmetrics.com/api/report/roas-evolution?account_id=000000000000000000001234&date_range=this_month&skip=0&limit=100&time_unit=daily", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
```
Response
Success Response (200 OK)
```json
{
"status": "ok",
"data": [
{
"_id": "2024-07-01",
"clicks": 1623,
"page_views": 10458,
"conversions": 117,
"microconversions": 441,
"revenue": 42466.97
},
{
"_id": "2024-07-02",
"clicks": 1845,
"page_views": 11258,
"conversions": 132,
"microconversions": 487,
"revenue": 38975.23
}
// Additional results...
]
}
```
Response Parameters
The response data array contains objects with the following fields:
Field | Type | Description |
_id | string | Date or time period identifier (format depends on time_unit parameter) |
clicks | number | Number of clicks during the time period |
page_views | number | Number of page views during the time period |
conversions | number | Number of conversions during the time period |
microconversions | number | Number of microconversions during the time period |
revenue | number | Total revenue generated during the time period |
Error Response (401 Unauthorized)
```json
{
"status": "error",
"message": "Unauthenticated"
}
```
### Error Response (400 Bad Request)
```json
{
"status": "error",
"message": "Missing required parameter: account_id"
}
```
Notes
- The `time_unit` parameter determines how data is aggregated in the response
- Use "daily" for detailed day-by-day analysis, "weekly" for week-over-week trends, or "monthly" for broader patterns
- This endpoint is particularly useful for visualizing performance trends over time
- Combine with UTM filters to analyze specific marketing channels or campaigns
- The data can be used to calculate ROAS by dividing revenue by advertising spend for each time period