list agent analytics pages.md
List Agent Analytics Pages
Returns the pages AI agents and bots read on a site in the date range, with visits per traffic type. Sorted by AI visits unless sort is set. With type, returns only pages that traffic type visited. With agent, returns only the pages that one coding agent read.
OpenAPI
openapi: 3.1.0
info:
title: Lightsage Public API
description: Public API for Lightsage CLI and external integrations.
version: 1.0.0
servers:
- url: https://api.lightsage.com
description: Production
security: []
tags:
- name: Status
description: Check API availability and validate the calling API key.
- name: Visibility
description: >-
Measure visibility, citations, competitors, and prompt performance across
answer platforms.
- name: Prompts
description: Manage tracked prompts and topics, and inspect their stored runs.
- name: Opportunities
description: Review ranked opportunities computed from prompt visibility results.
- name: Tasks
description: Manage the persisted action queue and task lifecycle.
- name: Site Audits
description: Review website audit results and page-level findings.
- name: Agent Analytics
description: >-
See which coding agents, AI bots, and people visit your tracked sites,
which pages they read, which pages return errors, and where the visits
come from.
- name: Evals
description: Define eval tasks, judges, subjects, and saved configurations.
- name: Eval Templates
description: >-
Select reusable judges, targets, schedules, metadata, and runtime settings
with `POST /v2/eval-templates`, then copy only those settings into
prompt-specific evals with `POST /v2/evals/batch`. Templates never contain
prompts and remain independent from evals created from them.
- name: Eval Runs
description: Start eval runs and inspect their lifecycle state.
- name: Eval Results
description: Review completed eval outcomes and diagnostic details.
- name: Agent Preference
description: >-
Compare your company head-to-head with a tracked competitor. Create a
comparison with `POST /v2/agent-preference/evals`, run it with `POST
/v2/eval-runs`, then read which company agents recommended.
- name: Agents
description: List runnable coding-agent harness and model combinations.
- name: Repositories
description: Manage reusable Git repository workspaces.
- name: Environments
description: List reusable runtime environments without exposing secret values.
- name: MCP Servers
description: List reusable MCP server integrations without exposing credentials.
- name: CLIs
description: List reusable command-line interfaces without exposing setup commands.
- name: Skills
description: List reusable skills available to workflows and evals.
paths:
/v2/agent-analytics/sites/{site_id}/pages:
get:
tags:
- Agent Analytics
summary: List Agent Analytics Pages
description: >-
Returns the pages AI agents and bots read on a site in the date range,
with visits per traffic type. Sorted by AI visits unless `sort` is set.
With `type`, returns only pages that traffic type visited. With `agent`,
returns only the pages that one coding agent read.
operationId: v2_agent_analytics_pages_list
parameters:
- name: site_id
in: path
required: true
schema:
type: string
title: Site Id
- name: start_date
in: query
required: false
schema:
type: string
format: date
title: Start Date
description: >-
Inclusive range start; defaults to 6 days before the end date. The
range may span at most 90 days.
- name: end_date
in: query
required: false
schema:
type: string
format: date
title: End Date
description: Inclusive range end in UTC; defaults to today.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 20
title: Limit
- name: search
in: query
required: false
schema:
type: string
maxLength: 200
title: Search
description: Only pages whose path contains this text.
- name: sort
in: query
required: false
schema:
enum:
- coding
- user
- search
- training
- other
- people
- ai_total
- last_seen
type: string
default: ai_total
title: Sort
description: >-
Traffic type to sort by, most visits first, or `last_seen` for the
latest visit first.
- name: type
in: query
required: false
schema:
type: string
enum:
- coding
- user
- search
- training
- other
- people
title: Type
description: Only pages this traffic type visited.
- name: agent
in: query
required: false
schema:
type: string
maxLength: 100
title: Agent
description: >-
Only pages this coding agent read, by the `name` the sources list
gives it, such as `codex` or `cursor`.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentAnalyticsPageListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
PublicAgentAnalyticsPageListResponse:
properties:
site_id:
type: string
title: Site Id
start_date:
type: string
format: date
title: Start Date
end_date:
type: string
format: date
title: End Date
agent:
anyOf:
- type: string
- type: 'null'
title: Agent
description: >-
The coding agent the pages were filtered to, when `agent` was set.
Its visits are in `coding` and `ai_total`; the other counts are 0.
pages:
items:
$ref: '#/components/schemas/PublicAgentTrafficPage'
type: array
title: Pages
type: object
required:
- site_id
- start_date
- end_date
title: PublicAgentAnalyticsPageListResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicAgentTrafficPage:
properties:
path:
type: string
title: Path
coding:
type: integer
title: Coding
description: Visits from coding agents such as Claude Code, Codex, and Cursor.
user:
type: integer
title: User
description: >-
Visits from AI assistants fetching a page because a user asked, such
as ChatGPT-User.
search:
type: integer
title: Search
description: Visits from AI search indexers such as OAI-SearchBot.
training:
type: integer
title: Training
description: Visits from AI training crawlers such as GPTBot.
other:
type: integer
title: Other
description: Visits from bots with no AI purpose, such as search engine crawlers.
people:
type: integer
title: People
description: Visits from people.
ai_total:
type: integer
title: Ai Total
description: Sum of `coding`, `user`, `search`, and `training` visits.
last_seen:
anyOf:
- type: string
- type: 'null'
title: Last Seen
description: Day of the latest visit, in `YYYY-MM-DD` format.
type: object
required:
- path
- coding
- user
- search
- training
- other
- people
- ai_total
title: PublicAgentTrafficPage
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
LightsageApiKeyAuth:
type: apiKey
in: header
name: X-Lightsage-Api-Key