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.
The paid deep audit is no longer offered and can't be purchased. The free scan is still available.
Bot Traffic by AttractOS