retrieve head to head.md
Retrieve Head To Head
Returns how often agents recommended your company over each tracked competitor: wins, losses, ties, and win rate per competitor plus a combined record. Calculated from the most recent attempts across all Agent Preference evals, up to limit; truncated reports whether older attempts were left out.
OpenAPI
/openapi.json get /v2/agent-preference/head-to-head
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-preference/head-to-head:
get:
tags:
- Agent Preference
summary: Retrieve Head To Head
description: >-
Returns how often agents recommended your company over each tracked
competitor: wins, losses, ties, and win rate per competitor plus a
combined record. Calculated from the most recent attempts across all
Agent Preference evals, up to `limit`; `truncated` reports whether older
attempts were left out.
operationId: v2_agent_preference_head_to_head_retrieve
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 500
title: Limit
description: Most recent attempts to include in the records.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/V2AgentPreferenceHeadToHeadResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
V2AgentPreferenceHeadToHeadResponse:
properties:
company:
$ref: '#/components/schemas/V2AgentPreferenceCompany'
description: Your company, the side every record is counted from.
summary:
$ref: '#/components/schemas/V2AgentPreferenceRecord'
description: Combined record across every competitor.
data:
items:
$ref: '#/components/schemas/V2AgentPreferenceMatchup'
type: array
title: Data
description: One record per competitor, most comparisons first.
count:
type: integer
title: Count
description: The number of items in `data`.
attempts_considered:
type: integer
title: Attempts Considered
description: >-
Recent attempts read to build the records. Attempts without a usable
recommendation are read but not counted as comparisons.
limit:
type: integer
title: Limit
truncated:
type: boolean
title: Truncated
description: True when older attempts exist beyond `limit` and were not counted.
type: object
required:
- company
- summary
- count
- attempts_considered
- limit
- truncated
title: V2AgentPreferenceHeadToHeadResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
V2AgentPreferenceCompany:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
type: object
title: V2AgentPreferenceCompany
V2AgentPreferenceRecord:
properties:
wins:
type: integer
title: Wins
description: Attempts where the agent recommended your company.
losses:
type: integer
title: Losses
description: Attempts where the agent recommended the competitor.
ties:
type: integer
title: Ties
description: Attempts where the agent recommended both equally or neither.
comparisons:
type: integer
title: Comparisons
description: '`wins + losses + ties`.'
win_rate:
anyOf:
- type: number
- type: 'null'
title: Win Rate
description: >-
`wins / comparisons` from 0 to 1. Null when there are no
comparisons.
type: object
required:
- wins
- losses
- ties
- comparisons
title: V2AgentPreferenceRecord
V2AgentPreferenceMatchup:
properties:
wins:
type: integer
title: Wins
description: Attempts where the agent recommended your company.
losses:
type: integer
title: Losses
description: Attempts where the agent recommended the competitor.
ties:
type: integer
title: Ties
description: Attempts where the agent recommended both equally or neither.
comparisons:
type: integer
title: Comparisons
description: '`wins + losses + ties`.'
win_rate:
anyOf:
- type: number
- type: 'null'
title: Win Rate
description: >-
`wins / comparisons` from 0 to 1. Null when there are no
comparisons.
competitor_id:
anyOf:
- type: string
- type: 'null'
title: Competitor Id
description: Null when the competitor is no longer tracked.
competitor_name:
type: string
title: Competitor Name
competitor_domain:
anyOf:
- type: string
- type: 'null'
title: Competitor Domain
eval_ids:
items:
type: string
type: array
title: Eval Ids
description: Agent Preference evals that contributed to this record.
type: object
required:
- wins
- losses
- ties
- comparisons
- competitor_name
title: V2AgentPreferenceMatchup
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