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

# List Signals

> Buying signals found in public meetings, such as a council agreeing to replace water meters, matched to the suppliers your API key may read. Results are ordered newest match first. Read-only: this endpoint never marks a signal as viewed or contacted.
Civic Marketplace grants signal access per supplier. A key with no signal access gets `403`.
To pull new signals on a schedule, page from the start and stop at the first `id` you already hold. The order follows when each signal was matched to the supplier, not its `id`, so compare ids for equality only. See [Syncing Data](/guides/syncing-data#syncing-signals).



## OpenAPI

````yaml GET /v1/signals
openapi: 3.1.0
info:
  title: CivicMarketplace Partner API
  version: 1.0.0
  description: |
    Read-only partner API for accessing contracts, solicitations, suppliers,
    reference taxonomy and, where granted, supplier signals. Authenticate with
    a partner-scoped API key.
  contact:
    name: CivicMarketplace Engineering
    email: engineering@civicmarketplace.com
servers:
  - url: https://api.civicmarketplace.com
    description: Production — `cmp_live_` keys
  - url: https://api.dev.civicmarketplace.com
    description: Sandbox — `cmp_test_` keys
security:
  - apiKey: []
tags:
  - name: Contracts
  - name: Solicitations
  - name: Suppliers
  - name: Taxonomy
  - name: Signals
paths:
  /v1/signals:
    get:
      tags:
        - Signals
      summary: List signals
      description: >-
        Buying signals found in public meetings, such as a council agreeing to
        replace water meters, matched to the suppliers your API key may read.
        Results are ordered newest match first. Read-only: this endpoint never
        marks a signal as viewed or contacted.

        Civic Marketplace grants signal access per supplier. A key with no
        signal access gets `403`.

        To pull new signals on a schedule, page from the start and stop at the
        first `id` you already hold. The order follows when each signal was
        matched to the supplier, not its `id`, so compare ids for equality only.
        See [Syncing Data](/guides/syncing-data#syncing-signals).
      parameters:
        - in: query
          name: supplier
          description: >-
            Supplier id (`sup_...`) to narrow the results to one supplier. A
            supplier the key may not read returns 404.
          schema:
            type: string
        - in: query
          name: cursor
          description: >-
            `meta.next_cursor` from the previous page. Omit it for the first
            page.
          schema:
            type: string
        - in: query
          name: limit
          description: Signals per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Signal page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalListResponse'
              example:
                data:
                  - id: sig_aj4k
                    supplier:
                      id: sup_1r
                      name: Acme Water Services
                    title: Water meter replacement
                    entity_name: City of Austin
                    state: TX
                    city: Austin
                    meeting_date: '2026-10-14'
                    description: >-
                      Council approved replacing 12,000 residential water meters
                      over two years and asked staff to bring back vendor
                      options by January.
                    estimated_amount: 125000.5
                    contact:
                      name: Jordan Lee
                      title: Utilities Director
                      email: jordan.lee@example.gov
                    matching_contracts:
                      - id: ctr_3f
                        name: Water Metering Equipment and Services
                    video_url: https://example.gov/meetings/2026-10-14
                    video_timestamp_seconds: 2715
                    status: new
                    contacted: false
                    not_relevant_note: null
                meta:
                  next_cursor: eyJpIjoxMjN9.c2ln
                  limit: 25
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            This API key has no signal access. Ask Civic Marketplace to enable
            it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: >-
                    this API key has no access to supplier signals; ask Civic
                    Marketplace to enable it
                  request_id: 3f1c2a9e-5b7d-4e8a-9c61-2d0f4b8e7a13
        '404':
          description: The `supplier` filter names a supplier this key may not read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: supplier not found
                  request_id: 3f1c2a9e-5b7d-4e8a-9c61-2d0f4b8e7a13
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SignalListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Signal'
        meta:
          $ref: '#/components/schemas/PageMeta'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - not_found
                - rate_limited
                - validation_failed
                - internal_error
            message:
              type: string
            request_id:
              type: string
    Signal:
      type: object
      required:
        - id
        - supplier
        - title
        - entity_name
        - state
        - city
        - meeting_date
        - description
        - estimated_amount
        - contact
        - matching_contracts
        - video_url
        - video_timestamp_seconds
        - status
        - contacted
        - not_relevant_note
      properties:
        id:
          type: string
          example: sig_aj4k
          description: >-
            Opaque. Compare for equality only: the order of results does not
            follow it. A partner granted several suppliers can see the same
            signal once per supplier, so key on `id` and `supplier.id`.
        supplier:
          description: The supplier this signal was matched to.
          allOf:
            - $ref: '#/components/schemas/NamedRef'
        title:
          type: string
          example: Water meter replacement
        entity_name:
          type: string
          description: The government entity that held the meeting.
          example: City of Austin
        state:
          type: string
          nullable: true
          example: TX
        city:
          type: string
          nullable: true
          example: Austin
        meeting_date:
          type: string
          format: date
          nullable: true
        description:
          type: string
          nullable: true
          description: The deal description, what the entity discussed buying.
        estimated_amount:
          type: number
          nullable: true
          description: Estimated deal value in US dollars.
          example: 125000.5
        contact:
          $ref: '#/components/schemas/SupplierSignalContact'
        matching_contracts:
          type: array
          description: >-
            Contracts the supplier holds that fit this signal. Empty when none
            do.
          items:
            $ref: '#/components/schemas/NamedRef'
        video_url:
          type: string
          nullable: true
          description: Recording of the meeting where the signal came up.
        video_timestamp_seconds:
          type: integer
          nullable: true
          description: Offset into `video_url` where the signal is discussed.
        status:
          type: string
          enum:
            - new
            - viewed
            - contacted
            - not_relevant
          description: >-
            The supplier's progress on this signal. `not_relevant` wins over
            `contacted`, which wins over `viewed`.
        contacted:
          type: boolean
          description: Whether the supplier has recorded getting in touch with the entity.
        not_relevant_note:
          type: string
          nullable: true
          description: The supplier's reason for marking the signal not relevant, if given.
    PageMeta:
      type: object
      required:
        - next_cursor
        - limit
      properties:
        next_cursor:
          type: string
          nullable: true
        limit:
          type: integer
    NamedRef:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
    SupplierSignalContact:
      type: object
      description: >-
        The point of contact at the government entity, when the meeting named
        one.
      required:
        - name
        - title
        - email
      properties:
        name:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
  responses:
    ValidationFailed:
      description: A query parameter is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: validation_failed
              message: invalid cursor
              request_id: 3f1c2a9e-5b7d-4e8a-9c61-2d0f4b8e7a13
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: unauthorized
              request_id: 3f1c2a9e-5b7d-4e8a-9c61-2d0f4b8e7a13
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: rate limit exceeded
              request_id: 3f1c2a9e-5b7d-4e8a-9c61-2d0f4b8e7a13
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: cmp_(live|test)_*

````

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