list agent analytics error pages.md
List Agent Analytics Error Pages
Returns the pages on a site that returned an error status (400 and up) in the date range, most error requests first, with the agents, bots, and people that got each error. Set status to 404 for pages that were not found. Needs server-side tracking that records status codes; status_codes_tracked says whether the site has any.
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}/error-pages:
get:
tags:
- Agent Analytics
summary: List Agent Analytics Error Pages
description: >-
Returns the pages on a site that returned an error status (400 and up)
in the date range, most error requests first, with the agents, bots, and
people that got each error. Set `status` to 404 for pages that were not
found. Needs server-side tracking that records status codes;
`status_codes_tracked` says whether the site has any.
operationId: v2_agent_analytics_error_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: 50
title: Limit
- name: status
in: query
required: false
schema:
type: integer
maximum: 599
minimum: 400
title: Status
description: Only this status code, such as 404.
- name: type
in: query
required: false
schema:
type: string
enum:
- coding
- user
- search
- training
- other
- people
title: Type
description: Only errors this traffic type got.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentAnalyticsErrorPageListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
PublicAgentAnalyticsErrorPageListResponse:
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
status_codes_tracked:
type: boolean
title: Status Codes Tracked
description: >-
Whether any request to the site in the date range reported a status
code. Status codes come from server-side tracking such as a log
drain or middleware; when this is false, an empty `pages` list does
not mean there were no errors.
pages:
items:
$ref: '#/components/schemas/PublicAgentErrorPage'
type: array
title: Pages
description: Most error requests first.
type: object
required:
- site_id
- start_date
- end_date
- status_codes_tracked
title: PublicAgentAnalyticsErrorPageListResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicAgentErrorPage:
properties:
path:
type: string
title: Path
status_code:
type: integer
title: Status Code
description: HTTP status returned, such as 404.
visits:
type: integer
title: Visits
description: Requests to this path that got this status.
ai_visits:
type: integer
title: Ai Visits
description: Of `visits`, those from coding agents and AI bots.
last_seen:
anyOf:
- type: string
- type: 'null'
title: Last Seen
description: Time of the latest error.
sources:
items:
$ref: '#/components/schemas/PublicAgentErrorSource'
type: array
title: Sources
description: Who got the error, most requests first.
type: object
required:
- path
- status_code
- visits
- ai_visits
title: PublicAgentErrorPage
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
PublicAgentErrorSource:
properties:
name:
type: string
title: Name
description: Agent or bot name, as in the traffic sources list, or `people`.
kind:
type: string
enum:
- agent
- bot
- other
- people
title: Kind
type:
type: string
enum:
- coding
- user
- search
- training
- other
- people
title: Type
visits:
type: integer
title: Visits
description: Requests from this source that got the error.
type: object
required:
- name
- kind
- type
- visits
title: PublicAgentErrorSource
securitySchemes:
LightsageApiKeyAuth:
type: apiKey
in: header
name: X-Lightsage-Api-Key