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

# List Signals

> Retrieve a paginated list of signals. Without filters, returns the most recent signals.

<Info>
  Each result is a lightweight **card** (identity + the central statement). For a signal's full
  verified decomposition (the flat `units[]` with evidence), call
  [**Get signal**](/api-reference/signals/get) with the `signal_id`.
</Info>


## OpenAPI

````yaml GET /v1/signals
openapi: 3.1.0
info:
  title: Gildea API
  description: >-
    Market intelligence on the AI economy, built for agents. Gildea ingests
    expert sources (podcasts, essays, VC memos, X posts, research papers, news)
    and decomposes them into verified, source-cited atomic facts: thesis
    sentences, argument sentences, summary sentences, and claims.


    **Key capabilities:**

    - Verified atomic facts with verbatim source citations

    - Entity intelligence with trend analytics across 8 entity types

    - Theme taxonomy (6 value-chain segments + 6 market forces)

    - Search verified text units by free-text query or by similarity to a known
    unit


    Only `verdict=pass` data is served. Every claim cites the source evidence it
    was extracted from.
  version: 0.1.0
servers:
  - url: https://api.gildea.ai
    description: Production
  - url: http://localhost:8000
    description: Local development
security:
  - ApiKeyAuth: []
tags:
  - name: signals
    description: >-
      Market intelligence signals — articles decomposed into verified text
      units.
  - name: entities
    description: >-
      Entity intelligence — companies, people, and products with trend
      analytics.
  - name: themes
    description: Taxonomy themes — value chain segments and market forces with trend stats.
  - name: search
    description: >-
      Search Gildea's verified text units — text queries or similarity to a
      known unit.
  - name: health
    description: Service health and status.
  - name: admin
    description: Administrative operations (requires admin secret).
paths:
  /v1/signals:
    get:
      tags:
        - signals
      summary: List signals
      description: >-
        Retrieve a paginated list of market intelligence signals. Without
        filters, returns the most recent signals sorted by date.
      operationId: list_signals_v1_signals_get
      parameters:
        - name: entity
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by entity public ID (`gld:/…`) or exact entity name
              (case-insensitive). Family-level and alias-aware (Sonnet / Claude
              3.5 resolve to Claude). Get public IDs from any `entity_id` field
              via GET /v1/entities. An unknown entity returns 404 (not an empty
              list), so a typo is distinguishable from a real no-match.
            title: Entity
          description: >-
            Filter by entity public ID (`gld:/…`) or exact entity name
            (case-insensitive). Family-level and alias-aware (Sonnet / Claude
            3.5 resolve to Claude). Get public IDs from any `entity_id` field
            via GET /v1/entities. An unknown entity returns 404 (not an empty
            list), so a typo is distinguishable from a real no-match.
        - name: theme
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by theme label (see GET /v1/themes for valid labels). An
              unknown label returns 404, not an empty list.
            title: Theme
          description: >-
            Filter by theme label (see GET /v1/themes for valid labels). An
            unknown label returns 404, not an empty list.
        - name: keyword
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Literal keyword filter on signal title and decomposition text
              (exact term match, not relevance-ranked). For natural-language
              semantic retrieval, use the `q` parameter on GET /v1/search
              instead.
            title: Keyword
          description: >-
            Literal keyword filter on signal title and decomposition text (exact
            term match, not relevance-ranked). For natural-language semantic
            retrieval, use the `q` parameter on GET /v1/search instead.
        - name: content_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - analysis
                  - event
              - type: 'null'
            description: 'Filter by content type: ''analysis'' or ''event''.'
            title: Content Type
          description: 'Filter by content type: ''analysis'' or ''event''.'
        - name: published_after
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: ISO 8601 date — only signals published after this date.
            title: Published After
          description: ISO 8601 date — only signals published after this date.
        - name: published_before
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: ISO 8601 date — only signals published before this date.
            title: Published Before
          description: ISO 8601 date — only signals published before this date.
        - name: window
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Relative time shortcut, e.g. `7d`, `2w`, `14d`, `1m` (d=days,
              w=weeks, m=30-day months). Sugar for `published_after = now -
              window`. Cannot be combined with `published_after`.
            title: Window
          description: >-
            Relative time shortcut, e.g. `7d`, `2w`, `14d`, `1m` (d=days,
            w=weeks, m=30-day months). Sugar for `published_after = now -
            window`. Cannot be combined with `published_after`.
        - name: sort
          in: query
          required: false
          schema:
            enum:
              - published
              - changed
            type: string
            description: >-
              Result ordering. `published` (default): newest published first,
              for browsing. `changed`: the monitor change-feed — signals ordered
              by when they last changed (oldest change first). Page it with
              `cursor` to pull everything that changed since your last sync
              (newly published AND reprocessed signals), in order, without
              missing or repeating any. The `cursor` and `sort` must stay
              consistent across a pagination sequence.
            default: published
            title: Sort
          description: >-
            Result ordering. `published` (default): newest published first, for
            browsing. `changed`: the monitor change-feed — signals ordered by
            when they last changed (oldest change first). Page it with `cursor`
            to pull everything that changed since your last sync (newly
            published AND reprocessed signals), in order, without missing or
            repeating any. The `cursor` and `sort` must stay consistent across a
            pagination sequence.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque cursor from a previous response's `next_cursor`. Omit for
              the first page.
            title: Cursor
          description: >-
            Opaque cursor from a previous response's `next_cursor`. Omit for the
            first page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: >-
              Page size (1–50, default 25). These endpoints are
              cursor-paginated: pass the returned `next_cursor` as `cursor` to
              walk the full result set. (Relevance-ranked GET /v1/search is not
              paginated — its `limit` is the total top-N returned, not a page
              size.)
            default: 25
            title: Limit
          description: >-
            Page size (1–50, default 25). These endpoints are cursor-paginated:
            pass the returned `next_cursor` as `cursor` to walk the full result
            set. (Relevance-ranked GET /v1/search is not paginated — its `limit`
            is the total top-N returned, not a page size.)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalListResponse'
                type: object
                additionalProperties: true
                title: Response List Signals V1 Signals Get
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SignalListResponse:
      properties:
        signals:
          items:
            $ref: '#/components/schemas/SignalCard'
          type: array
          title: Signals
          description: Signal cards matching the query.
        has_more:
          type: boolean
          title: Has More
          description: Whether more results are immediately available beyond this page.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Pass back as `cursor` to continue. For `sort=published` it is the
            next-page cursor (null once `has_more` is false). For `sort=changed`
            it is a resume point you keep and poll forward from: it is returned
            even on the last page (when `has_more` is false) so you can fetch
            future changes, and is null only when nothing changed (keep your
            prior cursor).
      type: object
      required:
        - signals
        - has_more
      title: SignalListResponse
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SignalCard:
      properties:
        signal_id:
          type: string
          title: Signal Id
          examples:
            - 0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        url:
          type: string
          title: Url
        published_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Published At
          description: Publication timestamp (ISO 8601).
        content_type:
          anyOf:
            - type: string
              enum:
                - analysis
                - event
            - type: 'null'
          title: Content Type
          examples:
            - analysis
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Source registrable domain.
          examples:
            - reuters.com
        verified_unit_count:
          type: integer
          title: Verified Unit Count
          description: >-
            Number of verified units in the decomposition (equals len(units) in
            detail). The honest depth signal — use this, not statement length,
            to gauge analytical depth.
          default: 0
        thesis:
          anyOf:
            - type: string
            - type: 'null'
          title: Thesis
          description: Central statement (analysis signals).
        synopsis:
          anyOf:
            - type: string
            - type: 'null'
          title: Synopsis
          description: Central statement (event signals).
        themes:
          $ref: '#/components/schemas/Themes'
        entities:
          items:
            $ref: '#/components/schemas/EntitySummary'
          type: array
          title: Entities
      type: object
      required:
        - signal_id
        - url
      title: SignalCard
      description: Lightweight signal for list views. Carries the central statement whole.
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code.
          examples:
            - not_found
        message:
          type: string
          title: Message
          description: Human-readable error description.
          examples:
            - Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found
        status:
          type: integer
          title: Status
          description: HTTP status code.
          examples:
            - 404
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
          description: 'For validation errors: path to the offending parameter.'
          examples:
            - body.text
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Correlation id (also on the X-Request-Id response header).
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After
          description: >-
            Seconds to wait before retrying (mirrors the Retry-After header).
            Present on 429 (rate limited) and 503 (temporarily unavailable).
        reset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reset
          description: >-
            Unix epoch seconds when the exceeded rate-limit window resets.
            Present on 429.
      type: object
      required:
        - code
        - message
        - status
      title: ErrorDetail
    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
    Themes:
      properties:
        value_chain:
          items:
            type: string
          type: array
          title: Value Chain
          examples:
            - - AI Infrastructure
        market_force:
          items:
            type: string
          type: array
          title: Market Force
          examples:
            - - Competitive Dynamics
      type: object
      title: Themes
    EntitySummary:
      properties:
        entity_id:
          type: string
          title: Entity Id
          description: Stable public entity ID.
          examples:
            - gld:/a1b2c3d4e5f6
        name:
          type: string
          title: Name
          examples:
            - NVIDIA
        type:
          type: string
          title: Type
          examples:
            - organization
      type: object
      required:
        - entity_id
        - name
        - type
      title: EntitySummary
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Include in every request as `X-API-Key:
        gld_your_key_here`.

````