> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onsomble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List discovered competitors

> Brands AI answers mention that this Site does not track — each with its name, inferred domain, kind, the reasoning behind the classification, an identification confidence, and how often it has been seen (first and last Scan, Scans measured). Filter by kind and Scan. Cursor-paginated. Track a brand in Onsomble to measure it; it then appears in the tracked list with the same competitorId.



## OpenAPI

````yaml /openapi/public-api-v1.json get /v1/sites/{siteId}/discovered-competitors
openapi: 3.0.0
info:
  title: Onsomble API
  description: >-
    Connect Onsomble to your reporting and operational workflows. Read
    discoverability results or start a Scan from another system.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.onsomble.ai
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Sites
    description: Sites connected to your account.
  - name: Clients
    description: Clients managed by agency accounts.
  - name: Scans
    description: Scan history, status, and controls.
  - name: Reports
    description: AI discoverability results.
paths:
  /v1/sites/{siteId}/discovered-competitors:
    get:
      tags:
        - Sites
      summary: List discovered competitors
      description: >-
        Brands AI answers mention that this Site does not track — each with its
        name, inferred domain, kind, the reasoning behind the classification, an
        identification confidence, and how often it has been seen (first and
        last Scan, Scans measured). Filter by kind and Scan. Cursor-paginated.
        Track a brand in Onsomble to measure it; it then appears in the tracked
        list with the same competitorId.
      operationId: listDiscoveredCompetitors
      parameters:
        - name: siteId
          required: true
          in: path
          schema:
            type: string
        - name: cursor
          required: false
          in: query
          description: >-
            Opaque cursor from the previous page (nextCursor). Omit for the
            first page.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 100
            default: 25
            type: number
        - name: kind
          required: false
          in: query
          description: >-
            Repeat to limit to these kinds. Omit for all, including brands with
            no classification.
          schema:
            type: array
            items:
              type: string
              enum:
                - direct_competitor
                - category_alternative
                - channel_or_broker
        - name: scanId
          required: false
          in: query
          description: >-
            Restrict to brands measured in this Scan. Omit for all-time
            presence.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveredCompetitorsListResponseDto'
        '404':
          description: Site or Scan not found.
components:
  schemas:
    DiscoveredCompetitorsListResponseDto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DiscoveredCompetitorDto'
        total:
          type: number
          description: Total discovered competitors matching the query.
        nextCursor:
          type: string
          nullable: true
          description: 'Opaque cursor: pass back as `cursor` for the next page.'
      required:
        - data
        - total
        - nextCursor
    DiscoveredCompetitorDto:
      type: object
      properties:
        competitorId:
          type: string
          format: uuid
          description: >-
            Stable id (brand identity). Track this brand in Onsomble to measure
            it; it then appears in the tracked catalogue with the same id.
        name:
          type: string
        domain:
          type: string
          nullable: true
        kind:
          type: string
          enum:
            - direct_competitor
            - category_alternative
            - channel_or_broker
          nullable: true
          description: How the discovery model classified the brand.
        reasoning:
          type: string
          nullable: true
          description: Why the AI answer treats this brand as a competitor.
        confidence:
          type: number
          nullable: true
          description: Identification confidence, 0 to 1.
        firstSeenAt:
          type: string
          nullable: true
          example: '2026-05-01'
          description: >-
            UTC calendar day of the first Scan that measured this brand. Use
            `firstSeenCompletedAt` for the exact time, to show the day in your
            user's time zone. Null when those Scans have no finalized date yet.
        firstSeenCompletedAt:
          type: string
          nullable: true
          format: date-time
          example: '2026-05-01T09:42:00.000Z'
          description: >-
            When the first Scan that measured this brand finished, as an ISO
            8601 UTC timestamp.
        lastSeenAt:
          type: string
          nullable: true
          example: '2026-09-04'
          description: >-
            UTC calendar day of the most recent Scan. Use `lastSeenCompletedAt`
            for the exact time, to show the day in your user's time zone. Null
            when not yet finalized.
        lastSeenCompletedAt:
          type: string
          nullable: true
          format: date-time
          example: '2026-09-04T09:42:00.000Z'
          description: >-
            When the most recent Scan that measured this brand finished, as an
            ISO 8601 UTC timestamp.
        scansSeen:
          type: number
          example: 18
          description: Scans that have measured it.
      required:
        - competitorId
        - name
        - domain
        - kind
        - reasoning
        - confidence
        - firstSeenAt
        - lastSeenAt
        - scansSeen
  securitySchemes:
    apiKeyAuth:
      scheme: bearer
      bearerFormat: ons_…
      type: http
      description: An API key created in Settings → Account → API Keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.