Stats

The Stats endpoint returns aggregated metrics for a site including total bot visits, LLM referrals, and conversions. It also provides breakdowns by bot name, referral source, and conversion event type—ideal for dashboard displays and reporting.

GET /api/v1/sites/{siteId}/stats

Get aggregated statistics for a site

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

Request

Get Site Stats

curl -X GET "https://attractos.com/api/v1/sites/site_abc123/stats?start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

const siteId = 'site_abc123';
const params = new URLSearchParams();
params.set('start', '2024-01-01');
params.set('end', '2024-01-31');

const url = 'https://attractos.com/api/v1/sites/' + siteId + '/stats?' + params;
const response = await fetch(url, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});

const data = await response.json();
console.log('Bot visits: ' + data.totals.bot_visits);
console.log('Referrals: ' + data.totals.referrals);

import requests

site_id = 'site_abc123'
response = requests.get(
    f'https://attractos.com/api/v1/sites/{site_id}/stats',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'start': '2024-01-01',
        'end': '2024-01-31',
    }
)

data = response.json()
print(f"Bot visits: {data['totals']['bot_visits']}")

# Print top referral sources
for source in data['referral_breakdown']:
    print(f"  {source['source']}: {source['count']}")

Response

200

{
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "totals": {
    "bot_visits": 8432,
    "referrals": 1256,
    "conversions": 89
  },
  "bot_breakdown": [
    { "bot_name": "GPTBot", "bot_company": "OpenAI", "count": 2341 },
    { "bot_name": "ClaudeBot", "bot_company": "Anthropic", "count": 1876 },
    { "bot_name": "PerplexityBot", "bot_company": "Perplexity", "count": 1523 },
    { "bot_name": "Googlebot", "bot_company": "Google", "count": 892 }
  ],
  "referral_breakdown": [
    { "source": "chatgpt", "count": 523 },
    { "source": "perplexity", "count": 312 },
    { "source": "claude", "count": 189 },
    { "source": "copilot", "count": 145 }
  ],
  "conversion_breakdown": [
    { "event_name": "signup", "count": 67, "value": 0 },
    { "event_name": "purchase", "count": 22, "value": 2189.78 }
  ]
}

Response Fields

Field	Type	Description
`period.start`	string	Start date of the data range
`period.end`	string	End date of the data range
`totals.bot_visits`	integer	Total AI bot crawls detected
`totals.referrals`	integer	Total LLM referral clicks
`totals.conversions`	integer	Total conversion events tracked
`bot_breakdown[]`	array	Bot visits grouped by bot name, sorted by count
`referral_breakdown[]`	array	Referrals grouped by LLM source, sorted by count
`conversion_breakdown[]`	array	Conversions grouped by event name with total value

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

What does the stats endpoint include?

Total counts for bot visits, referrals, and conversions, plus breakdowns by bot name, LLM source, and conversion event type within the specified date range.

How often is stats data updated?

Stats are calculated in real-time. New events appear immediately in the response.

Can I get stats for multiple sites in one request?

No, each request is scoped to a single site. Make separate requests per site if you need data for multiple sites.