Events
The Events endpoint returns individual tracking events with full details. Query raw bot visits, LLM referrals, and conversions with cursor-based pagination. Use this for detailed analysis, data exports, or building custom dashboards.
GET
/api/v1/sites/{siteId}/events Query individual events with pagination
Path Parameters
Path
| Name | Type | Description |
|---|---|---|
siteId required | string | The site ID from the /sites endpoint |
Query Parameters
Query
| Name | Type | Description |
|---|---|---|
start | string Default: 7 days ago | Start date in YYYY-MM-DD format |
end | string Default: today | End date in YYYY-MM-DD format |
type | string | Filter by event type: bot, referral, or conversion |
limit | integer Default: 100 | Maximum events to return (1-1000) |
cursor | string | Pagination cursor from previous response |
Request
Query Events
# Get latest referral events
curl -X GET "https://attractos.com/api/v1/sites/site_abc123/events?type=referral&limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"
# Paginate through results
curl -X GET "https://attractos.com/api/v1/sites/site_abc123/events?cursor=eyJpZCI6MTIzNH0" \
-H "Authorization: Bearer YOUR_API_KEY"async function getAllConversions(siteId, startDate, endDate) {
const events = [];
let cursor = null;
do {
const params = new URLSearchParams();
params.set('type', 'conversion');
params.set('start', startDate);
params.set('end', endDate);
params.set('limit', '1000');
if (cursor) params.set('cursor', cursor);
const url = 'https://attractos.com/api/v1/sites/' + siteId + '/events?' + params;
const response = await fetch(url, {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
const data = await response.json();
events.push(...data.events);
cursor = data.next_cursor;
} while (cursor);
return events;
}import requests
def get_all_events(site_id, event_type=None, start=None, end=None):
events = []
cursor = None
while True:
params = {'limit': 1000}
if event_type:
params['type'] = event_type
if start:
params['start'] = start
if end:
params['end'] = end
if cursor:
params['cursor'] = cursor
response = requests.get(
f'https://attractos.com/api/v1/sites/{site_id}/events',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params=params
)
data = response.json()
events.extend(data['events'])
cursor = data.get('next_cursor')
if not cursor:
break
return events Response
Response
200{
"events": [
{
"id": 45678,
"type": "bot",
"page_path": "/guides/remote-work",
"country": "US",
"created_at": "2024-01-15T14:32:18.000Z",
"bot_name": "GPTBot",
"bot_company": "OpenAI"
},
{
"id": 45677,
"type": "referral",
"page_path": "/blog/best-tools",
"country": "GB",
"created_at": "2024-01-15T14:28:45.000Z",
"source": "chatgpt"
},
{
"id": 45676,
"type": "conversion",
"page_path": "/checkout/success",
"country": "US",
"created_at": "2024-01-15T14:25:12.000Z",
"event_name": "purchase",
"event_value": 99.99
}
],
"next_cursor": "eyJpZCI6NDU2NzUsImNyZWF0ZWRBdCI6IjIwMjQtMDEtMTVUMTQ6MjA6MDAuMDAwWiJ9"
} Event Object Fields
| Field | Type | Description |
|---|---|---|
id | integer | Unique event identifier |
type | string | "bot", "referral", or "conversion" |
page_path | string | The page where the event occurred |
country | string | ISO country code (e.g., "US", "GB") |
created_at | string | ISO 8601 timestamp of the event |
Bot Event Fields
| Field | Type | Description |
|---|---|---|
bot_name | string | Name of the bot (e.g., "GPTBot") |
bot_company | string | Company operating the bot (e.g., "OpenAI") |
Referral Event Fields
| Field | Type | Description |
|---|---|---|
source | string | LLM source (e.g., "chatgpt", "claude") |
Conversion Event Fields
| Field | Type | Description |
|---|---|---|
event_name | string | Name of the conversion event |
event_value | number | Optional monetary value (null if not set) |
Errors
400 MISSING_SITE_ID Site ID not provided in path 403 SITE_NOT_FOUND Site doesn't exist or you don't have access 429 RATE_LIMITED Too many requests Frequently Asked Questions
How do I paginate through all events?
Use the
next_cursor from each response as the cursor parameter in the next request. Continue until next_cursor is null.What is the maximum date range I can query?
There's no hard limit, but larger date ranges return more data and take longer. For best performance, query in chunks of 30 days or less.
Can I filter by multiple event types?
Not in a single request. Make separate requests with different
type parameters, or omit the filter to get all types.