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

# List contact stats

> Confirmed, non-deleted inspections. Revenue is the inspection price.

<Note>
  **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon.
</Note>


## OpenAPI

````yaml /api/openapi.json get /v1/contacts/stats
openapi: 3.1.0
info:
  title: Hive Inspect API
  version: 1.0.0
  description: Connect other tools to your Hive Inspect contacts, inspections and events.
servers:
  - url: https://api.hiveinspect.com
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Agents, clients and every other contact in your organization.
  - name: Agencies
    description: The brokerages your agents belong to. Read-only.
  - name: Inspections
    description: Read-only access to your inspections.
  - name: Attachments
    description: Additional reports and additional documents on an inspection.
  - name: Events
    description: Extra appointments on an inspection, such as a radon drop-off or pick-up.
paths:
  /v1/contacts/stats:
    get:
      tags:
        - Contacts
      summary: List contact stats
      description: Confirmed, non-deleted inspections. Revenue is the inspection price.
      operationId: listContactStats
      parameters:
        - name: role
          in: query
          required: false
          description: >-
            Count only inspections where the contact had this role (default: any
            role): agent, client, or an exact role
          schema:
            type: string
        - name: contact_id
          in: query
          required: false
          description: Stats for one contact
          schema:
            type: string
            format: uuid
        - name: contact_ids
          in: query
          required: false
          description: Comma-separated contact ids (up to 200)
          schema:
            type: string
        - name: agency_id
          in: query
          required: false
          description: Only contacts linked to this agency
          schema:
            type: string
            format: uuid
        - name: search
          in: query
          required: false
          description: Name, email, agency name, or phone (3+ digits) contains
          schema:
            type: string
        - name: tag
          in: query
          required: false
          description: Only contacts with any of these tag names; repeat for several
          schema:
            type: array
            items:
              type: string
        - name: inspection_after
          in: query
          required: false
          description: >-
            ISO 8601 date or timestamp; count only inspections at/after this
            time
          schema:
            type: string
        - name: inspection_before
          in: query
          required: false
          description: ISO 8601 date or timestamp; count only inspections before this time
          schema:
            type: string
        - name: first_inspection_after
          in: query
          required: false
          description: >-
            ISO 8601 date or timestamp; contacts whose first inspection is
            at/after this time
          schema:
            type: string
        - name: first_inspection_before
          in: query
          required: false
          description: >-
            ISO 8601 date or timestamp; contacts whose first inspection is
            before this time
          schema:
            type: string
        - name: inactive_after
          in: query
          required: false
          description: >-
            With inactive_before: contacts with inspections, but none in this
            range
          schema:
            type: string
        - name: inactive_before
          in: query
          required: false
          description: 'With inactive_after: end of the inactive range'
          schema:
            type: string
        - name: birthday_after
          in: query
          required: false
          description: MM-DD; birthdays on/after this day of the year
          schema:
            type: string
        - name: birthday_before
          in: query
          required: false
          description: MM-DD; birthdays on/before this day of the year
          schema:
            type: string
        - name: paid_only
          in: query
          required: false
          description: Count only paid inspections
          schema:
            type: boolean
        - name: sort
          in: query
          required: false
          description: >-
            total_inspections, buying_agent_inspections,
            listing_agent_inspections, client_inspections, total_revenue,
            buying_agent_revenue, listing_agent_revenue, first_inspection_at,
            last_inspection_at, first_name or last_name; prefix '-' for
            descending
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description: '`next_cursor` from the previous page'
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1-200 (default 50)
          schema:
            type: integer
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactStatsList'
        '400':
          description: Invalid parameter
        '401':
          description: Missing, invalid or inactive API key
        '429':
          description: Rate limit exceeded (120 requests/minute per key owner)
components:
  schemas:
    ContactStatsList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContactStats'
        next_cursor:
          type:
            - string
            - 'null'
        total:
          type: integer
          description: Every record matching the filters, across all pages
      example:
        data:
          - contact_id: 0b6f2c1e-7d1a-4c55-9a5e-2f3b8c1d4e6f
            first_name: Dana
            last_name: Reyes
            email: dana@example.com
            agency_id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
            agency_name: Lone Star Realty
            total_inspections: 14
            buying_agent_inspections: 11
            listing_agent_inspections: 3
            client_inspections: 0
            total_revenue: 6890
            buying_agent_revenue: 5415
            listing_agent_revenue: 1475
            first_inspection_at: '2026-03-09T14:00:00Z'
            last_inspection_at: '2026-09-24T16:00:00Z'
            upcoming_inspections_30d: 2
            inspection_count: 14
            revenue: 6890
        next_cursor: null
        total: 1
    ContactStats:
      type: object
      properties:
        contact_id:
          type: string
          format: uuid
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        agency_name:
          type:
            - string
            - 'null'
        total_inspections:
          type: integer
        buying_agent_inspections:
          type: integer
        listing_agent_inspections:
          type: integer
        client_inspections:
          type: integer
        total_revenue:
          type: number
        buying_agent_revenue:
          type: number
        listing_agent_revenue:
          type: number
        first_inspection_at:
          type:
            - string
            - 'null'
          format: date-time
        last_inspection_at:
          type:
            - string
            - 'null'
          format: date-time
        upcoming_inspections_30d:
          type: integer
        inspection_count:
          type: integer
          description: Same as total_inspections
        revenue:
          type: number
          description: Same as total_revenue
        agency_id:
          type:
            - string
            - 'null'
          format: uuid
      example:
        contact_id: 0b6f2c1e-7d1a-4c55-9a5e-2f3b8c1d4e6f
        first_name: Dana
        last_name: Reyes
        email: dana@example.com
        agency_id: 6c5b4a39-2817-4f6e-9d0c-8b7a6f5e4d3c
        agency_name: Lone Star Realty
        total_inspections: 14
        buying_agent_inspections: 11
        listing_agent_inspections: 3
        client_inspections: 0
        total_revenue: 6890
        buying_agent_revenue: 5415
        listing_agent_revenue: 1475
        first_inspection_at: '2026-03-09T14:00:00Z'
        last_inspection_at: '2026-09-24T16:00:00Z'
        upcoming_inspections_30d: 2
        inspection_count: 14
        revenue: 6890
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key from Business Tools → API Access.

````

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