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

Requires API key 60/min (Free) ยท 600/min (Pro)

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.
Bot Traffic by AttractOS