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

# List leads

> Reads leads in the selected workspace. Filter with `q`, a JSON object of field matches. Reads only: writes through this route are refused for every entity and every credential.



## OpenAPI

````yaml /openapi.json get /api/entities/Lead
openapi: 3.1.0
info:
  title: Reputably API
  version: 1.0.0
  description: >-
    The HTTP surface an agent credential can reach. It is read plus safe writes:
    you can read your reputation data, generate drafts, queue reports and run
    first-time tracking setup. You cannot send anything to an external platform,
    trigger syncs, touch billing or manage credentials.


    The same endpoints back the MCP server, so anything documented here is
    reachable both ways.
servers:
  - url: https://app.reputably.net
    description: Reputably
  - url: https://your-domain.example
    description: Your own verified white-label domain
security:
  - agentKey: []
tags:
  - name: Businesses
    description: The locations you track, their plan usage and AI-generated insights.
  - name: Reviews
    description: Google and Facebook reviews, including which still need a reply.
  - name: Brand mentions
    description: Mentions across X, Reddit, YouTube, Facebook communities and the open web.
  - name: Brand tracking
    description: The trackers that find mentions, and competitor share of voice.
  - name: Leads
    description: Buying signals detected in mentions, with the public post to reply to.
  - name: AI Visibility
    description: >-
      Whether AI assistants recommend the business, what they cite, and how it
      moves.
  - name: AI Traffic
    description: Which AI crawlers read the website, and who arrives from an AI answer.
  - name: Posts
    description: Google Business Profile posts and drafts.
  - name: Reports
    description: Queued report renders and their CSV output.
  - name: Setup
    description: First-time tracking configuration.
  - name: Account
    description: Workspaces, notifications, sync status and prospect audits.
paths:
  /api/entities/Lead:
    get:
      tags:
        - Leads
      summary: List leads
      description: >-
        Reads leads in the selected workspace. Filter with `q`, a JSON object of
        field matches. Reads only: writes through this route are refused for
        every entity and every credential.
      operationId: listLead
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: JSON filter object, for example {"needs_response":true}.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
          description: Field to sort on.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Maximum rows to return.
        - name: skip
          in: query
          required: false
          schema:
            type: integer
          description: Rows to skip, for paging.
        - name: X-Workspace-Id
          in: header
          required: false
          schema:
            type: string
          description: >-
            Which workspace to read. Omit it and you get the account’s home
            workspace, which on an agency account is often not where the live
            businesses are. A workspace this credential cannot read is refused
            with 403 rather than quietly answered from the default.
      responses:
        '200':
          description: Matching leads.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Lead'
        '401':
          description: Missing or invalid credential.
        '403':
          description: Not readable by this credential, or not in this workspace.
components:
  schemas:
    Lead:
      type: object
      title: Lead
      properties:
        id:
          type: string
          description: Unique id.
        mention_id:
          type: string
        tracker_id:
          type: string
        location_id:
          type: string
        intent_score:
          type: number
        intent_reason:
          type: string
        stage:
          type: string
          enum:
            - new
            - contacted
            - qualified
            - won
            - lost
        stage_changed_at:
          type: string
        notes:
          type: string
        assigned_to:
          type: string
        lost_reason:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        email:
          type: string
        suburb:
          type: string
        postcode:
          type: string
        source:
          type: string
        is_archived:
          type: boolean
        archived_at:
          type: string
        seen_at:
          type: string
        stale_post:
          type: boolean
          description: >-
            Internal visibility flag, NOT a client notification: the source post
            was already older than LEAD_STALE_POST_FLAG_DAYS (default 30) when
            we discovered it. Stamped once at dispatch time by
            lib/notificationChannels.js and never recomputed — the fact worth
            keeping is 'the post was already this old when we found it', which a
            live now-minus-posted_at would lose as the lead ages on the board.
            ~2/day in practice, almost all Reddit threads that are topically
            correct but commercially dead.
        stale_post_age_days:
          type: number
          description: >-
            Age of the source post in days at the moment the lead was
            dispatched. Set alongside stale_post. Deepest observed: 5,408 days
            (a 2011 r/australia thread).
  securitySchemes:
    agentKey:
      type: http
      scheme: bearer
      description: >-
        An agent key (`rpk_...`) created in Settings → API & MCP, sent as
        `Authorization: Bearer rpk_...`. Bearer only: a cookie session can never
        drive this API. An OAuth 2.1 access token obtained from the same host
        works identically and lands on the same ceiling.

````