retrieve agent analytics summary.md
Retrieve Agent Analytics Summary
Returns a site's visits by traffic type (coding agents, user-requested AI fetches, AI search, AI training, other bots, and people) for the date range and for the same number of days before it.
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}/summary:
get:
tags:
- Agent Analytics
summary: Retrieve Agent Analytics Summary
description: >-
Returns a site's visits by traffic type (coding agents, user-requested
AI fetches, AI search, AI training, other bots, and people) for the date
range and for the same number of days before it.
operationId: v2_agent_analytics_summary_retrieve
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.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAgentAnalyticsSummary'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
PublicAgentAnalyticsSummary:
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
current:
$ref: '#/components/schemas/PublicAgentTrafficTotals'
description: Visits from `start_date` through `end_date`.
previous:
$ref: '#/components/schemas/PublicAgentTrafficTotals'
description: >-
Visits over the same number of days just before `start_date`, for
comparison.
type: object
required:
- site_id
- start_date
- end_date
- current
- previous
title: PublicAgentAnalyticsSummary
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicAgentTrafficTotals:
properties:
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.
total:
type: integer
title: Total
description: Every visit, AI or not.
type: object
required:
- coding
- user
- search
- training
- other
- people
- ai_total
- total
title: PublicAgentTrafficTotals
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