> ## Documentation Index > Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 ````yaml /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: 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.