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

# Get search results

> Read saved search results in the order they become available. Each result contains an answer, source details, and supporting evidence. Read the next page using next_cursor; continue polling while terminal is false. Reading results does not start more calls. rank preserves each source's relevance rank.

Read answers in `results[].content`, with source details and supporting `evidence`. Requested structured fields appear in `output`.

Pass `next_cursor` as `cursor` to read the next page. Keep polling while `terminal` is false; finish reading when `terminal` is true and `has_more` is false. Results arrive as they become available, with their relevance `rank` preserved.

An answer can be partial or null. Check `content` and any requested `output` fields before using them.


## OpenAPI

````yaml api-reference/openapi.json GET /search/{id}/results
openapi: 3.0.3
info:
  title: Thred API
  version: 2.0.0
  description: >-
    Retrieve information over the phone for your app or AI assistant. Submit a
    search query and read answers asynchronously, with source details and
    supporting evidence. API keys select workspace and environment.
servers:
  - url: https://api.thred.dev
    description: Thred API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify the workspace and environment selected by your API key.
  - name: Usage
    description: Read daily operational usage.
  - name: Health
    description: Check public API availability.
  - name: Search
    description: >-
      Search for answers over the phone, with source details and supporting
      evidence.
paths:
  /search/{id}/results:
    get:
      tags:
        - Search
      summary: Get search results
      description: >-
        Read saved search results in the order they become available. Each
        result contains an answer, source details, and supporting evidence. Read
        the next page using next_cursor; continue polling while terminal is
        false. Reading results does not start more calls. rank preserves each
        source's relevance rank.
      operationId: getSearchResults
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: ^search_[a-z0-9-]+$
          description: Search ID returned by POST /search.
          example: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Maximum number of published results to return on this page.
          example: 2
        - name: cursor
          in: query
          schema:
            type: string
          description: >-
            Opaque next_cursor from a previous page of this search. Omit it to
            start at the first published outcome.
      responses:
        '200':
          description: Saved search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultsPage'
              examples:
                Completed search:
                  summary: Completed search
                  description: >-
                    Two complete answers from fictional sources. No custom
                    output was requested.
                  value:
                    id: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
                    status: completed
                    results:
                      - id: k17f0yc20e0v9g8g7hh76m6s7s9a5d2q
                        rank: 1
                        business:
                          name: Example Electronics
                          url: https://example.com/electronics
                          phone: '+15125550123'
                          address: Austin, TX
                        status: completed
                        call_id: call_828544bf-9508-4147-b056-6198c3f2998a
                        outcome: null
                        content: >-
                          Example Electronics has the Nintendo Switch 2 in stock
                          for pickup today until 6 p.m. Central Time.
                        evidence:
                          - type: call
                            call_id: call_828544bf-9508-4147-b056-6198c3f2998a
                            quote: >-
                              We have Nintendo Switch 2 consoles in stock. You
                              can pick one up today until 6 p.m. Central Time.
                            at_seconds: 18.2
                        sources:
                          - url: https://example.com/electronics
                            title: Example Electronics contact details
                            phoneExcerpt: Call +1 512-555-0123
                        verified_at: '2026-11-12T15:00:12Z'
                        completed_at: '2026-11-12T15:02:10Z'
                        error: null
                      - id: k17b3a1s4c6d8e0f2g5h7j9k1m3n5p7q
                        rank: 2
                        business:
                          name: Example Games
                          url: https://example.com/games
                          phone: '+15125550124'
                          address: Austin, TX
                        status: completed
                        call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
                        outcome: null
                        content: >-
                          Example Games has the Nintendo Switch 2 in stock for
                          pickup today until 8 p.m. Central Time.
                        evidence:
                          - type: call
                            call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
                            quote: >-
                              The Nintendo Switch 2 is in stock. Pickup is
                              available today until 8 p.m. Central Time.
                            at_seconds: 24.5
                        sources:
                          - url: https://example.com/games
                            title: Example Games contact details
                            phoneExcerpt: Call +1 512-555-0124
                        verified_at: '2026-11-12T15:00:15Z'
                        completed_at: '2026-11-12T15:03:05Z'
                        error: null
                    next_cursor: >-
                      WyJzZWFyY2hfNmM0NzlhMzAtY2YwNi00ZGJhLThkYzktMmQyODkzYmJjNjRmIiwyXQ==
                    has_more: false
                    terminal: true
                Structured answers:
                  summary: Completed search with structured fields
                  description: >-
                    The same completed search with the in_stock and
                    pickup_details fields requested in output.
                  value:
                    id: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
                    status: completed
                    results:
                      - id: k17f0yc20e0v9g8g7hh76m6s7s9a5d2q
                        rank: 1
                        business:
                          name: Example Electronics
                          url: https://example.com/electronics
                          phone: '+15125550123'
                          address: Austin, TX
                        status: completed
                        call_id: call_828544bf-9508-4147-b056-6198c3f2998a
                        outcome: null
                        content: >-
                          Example Electronics has the Nintendo Switch 2 in stock
                          for pickup today until 6 p.m. Central Time.
                        evidence:
                          - type: call
                            call_id: call_828544bf-9508-4147-b056-6198c3f2998a
                            quote: >-
                              We have Nintendo Switch 2 consoles in stock. You
                              can pick one up today until 6 p.m. Central Time.
                            at_seconds: 18.2
                        sources:
                          - url: https://example.com/electronics
                            title: Example Electronics contact details
                            phoneExcerpt: Call +1 512-555-0123
                        verified_at: '2026-11-12T15:00:12Z'
                        completed_at: '2026-11-12T15:02:10Z'
                        error: null
                        output:
                          in_stock: true
                          pickup_details: Pickup today until 6 p.m. Central Time.
                      - id: k17b3a1s4c6d8e0f2g5h7j9k1m3n5p7q
                        rank: 2
                        business:
                          name: Example Games
                          url: https://example.com/games
                          phone: '+15125550124'
                          address: Austin, TX
                        status: completed
                        call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
                        outcome: null
                        content: >-
                          Example Games has the Nintendo Switch 2 in stock for
                          pickup today until 8 p.m. Central Time.
                        evidence:
                          - type: call
                            call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
                            quote: >-
                              The Nintendo Switch 2 is in stock. Pickup is
                              available today until 8 p.m. Central Time.
                            at_seconds: 24.5
                        sources:
                          - url: https://example.com/games
                            title: Example Games contact details
                            phoneExcerpt: Call +1 512-555-0124
                        verified_at: '2026-11-12T15:00:15Z'
                        completed_at: '2026-11-12T15:03:05Z'
                        error: null
                        output:
                          in_stock: true
                          pickup_details: Pickup today until 8 p.m. Central Time.
                    next_cursor: >-
                      WyJzZWFyY2hfNmM0NzlhMzAtY2YwNi00ZGJhLThkYzktMmQyODkzYmJjNjRmIiwyXQ==
                    has_more: false
                    terminal: true
          headers:
            X-Request-ID:
              description: >-
                Server-generated request identifier for correlating this
                response.
              schema:
                type: string
                format: uuid
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    SearchResultsPage:
      type: object
      required:
        - id
        - status
        - results
        - next_cursor
        - has_more
        - terminal
      properties:
        id:
          type: string
          pattern: ^search_[a-z0-9-]+$
          description: Search ID associated with this page.
          example: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
        status:
          type: string
          enum:
            - discovering
            - running
            - canceling
            - completed
            - failed
            - canceled
            - expired
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
          maxItems: 100
        next_cursor:
          type: string
          description: >-
            Use for the next page or poll this cursor for future results.
            Returned even on an empty page.
        has_more:
          type: boolean
          description: >-
            More saved results exist now. False does not imply the search has
            finished.
        terminal:
          type: boolean
          description: No future results will be published for this search.
      example:
        id: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
        status: completed
        results:
          - id: k17f0yc20e0v9g8g7hh76m6s7s9a5d2q
            rank: 1
            business:
              name: Example Electronics
              url: https://example.com/electronics
              phone: '+15125550123'
              address: Austin, TX
            status: completed
            call_id: call_828544bf-9508-4147-b056-6198c3f2998a
            outcome: null
            content: >-
              Example Electronics has the Nintendo Switch 2 in stock for pickup
              today until 6 p.m. Central Time.
            evidence:
              - type: call
                call_id: call_828544bf-9508-4147-b056-6198c3f2998a
                quote: >-
                  We have Nintendo Switch 2 consoles in stock. You can pick one
                  up today until 6 p.m. Central Time.
                at_seconds: 18.2
            sources:
              - url: https://example.com/electronics
                title: Example Electronics contact details
                phoneExcerpt: Call +1 512-555-0123
            verified_at: '2026-11-12T15:00:12Z'
            completed_at: '2026-11-12T15:02:10Z'
            error: null
          - id: k17b3a1s4c6d8e0f2g5h7j9k1m3n5p7q
            rank: 2
            business:
              name: Example Games
              url: https://example.com/games
              phone: '+15125550124'
              address: Austin, TX
            status: completed
            call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
            outcome: null
            content: >-
              Example Games has the Nintendo Switch 2 in stock for pickup today
              until 8 p.m. Central Time.
            evidence:
              - type: call
                call_id: call_946bf0ce-c7f6-497d-971b-aa77dcce9016
                quote: >-
                  The Nintendo Switch 2 is in stock. Pickup is available today
                  until 8 p.m. Central Time.
                at_seconds: 24.5
            sources:
              - url: https://example.com/games
                title: Example Games contact details
                phoneExcerpt: Call +1 512-555-0124
            verified_at: '2026-11-12T15:00:15Z'
            completed_at: '2026-11-12T15:03:05Z'
            error: null
        next_cursor: WyJzZWFyY2hfNmM0NzlhMzAtY2YwNi00ZGJhLThkYzktMmQyODkzYmJjNjRmIiwyXQ==
        has_more: false
        terminal: true
    SearchResult:
      type: object
      properties:
        id:
          type: string
          description: Opaque identifier for this result.
        rank:
          type: integer
          minimum: 1
          description: >-
            Relevance rank assigned when the source was selected. Results are
            returned in the order they become available.
          maximum: 100
        business:
          type: object
          properties:
            name:
              type: string
            url:
              type: string
            phone:
              type: string
            address:
              type: string
          required:
            - name
            - url
            - phone
            - address
          description: 'Source metadata: name, URL, phone number, and address.'
        status:
          type: string
          enum:
            - completed
            - incomplete
            - failed
            - canceled
          description: >-
            Processing outcome for this source. A completed result can still
            have null content or output when no supporting transcript evidence
            was verified.
        call_id:
          type: string
          nullable: true
          description: >-
            Identifier of the call associated with this result, or null when no
            call was created.
        content:
          type: string
          nullable: true
          description: >-
            Concise natural-language answer to the query supported by verified
            transcript evidence. Null when no supported answer is available,
            including when processing has completed.
        output:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Values for the custom fields explicitly supplied in request.output.
            Partial results may omit unknown fields. Null when values or
            supporting transcript evidence are unavailable. This property is
            omitted when request.output is absent.
        evidence:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - call
              call_id:
                type: string
              quote:
                type: string
                description: Verbatim excerpt from the contact transcript.
              at_seconds:
                type: number
                minimum: 0
                description: >-
                  Start time of the matching transcript segment, in seconds from
                  the call timeline.
            required:
              - type
              - call_id
              - quote
              - at_seconds
          description: Supporting excerpts verified against the saved contact transcript.
        sources:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              title:
                type: string
              phoneExcerpt:
                type: string
            required:
              - url
              - title
              - phoneExcerpt
          description: Links used to verify the contact information.
        verified_at:
          type: string
          format: date-time
          description: >-
            When the source identity and phone number were verified; this is not
            the time the answer was obtained.
        completed_at:
          type: string
          format: date-time
          description: >-
            Call finalization timestamp, or the outcome publication time when no
            call finalization timestamp is available.
        error:
          type: string
          nullable: true
          description: >-
            Result-level error code as a string, or null when no result-level
            error was recorded.
        outcome:
          type: string
          nullable: true
          description: Underlying call termination reason when available, or null.
      description: >-
        A published search result. content is the concise natural-language
        answer, or null when no supported answer is available. output is
        included only when the search request explicitly supplies a custom
        output schema.
      required:
        - id
        - rank
        - business
        - status
        - call_id
        - content
        - evidence
        - sources
        - verified_at
        - completed_at
        - error
        - outcome
      example:
        id: k17f0yc20e0v9g8g7hh76m6s7s9a5d2q
        rank: 1
        business:
          name: Example Electronics
          url: https://example.com/electronics
          phone: '+15125550123'
          address: Austin, TX
        status: completed
        call_id: call_828544bf-9508-4147-b056-6198c3f2998a
        outcome: null
        content: >-
          Example Electronics has the Nintendo Switch 2 in stock for pickup
          today until 6 p.m. Central Time.
        evidence:
          - type: call
            call_id: call_828544bf-9508-4147-b056-6198c3f2998a
            quote: >-
              We have Nintendo Switch 2 consoles in stock. You can pick one up
              today until 6 p.m. Central Time.
            at_seconds: 18.2
        sources:
          - url: https://example.com/electronics
            title: Example Electronics contact details
            phoneExcerpt: Call +1 512-555-0123
        verified_at: '2026-11-12T15:00:12Z'
        completed_at: '2026-11-12T15:02:10Z'
        error: null
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          description: >-
            Request-level error details with a machine-readable code and a
            message.
  responses:
    BadRequest:
      description: >-
        Invalid JSON, query, options, output fields, cursor, webhook, or date
        range. Inspect error.code and error.message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Missing, malformed, invalid, revoked, or environment-mismatched bearer
        API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        No matching search in this key’s workspace and environment, or the
        endpoint does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: >-
        The service or required environment configuration is unavailable. Codes
        include calling_unavailable, environment_unavailable, not_configured,
        and backend_unavailable. Inspect error.code and error.message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Thred API key
      description: >-
        Send Authorization: Bearer <THRED_API_KEY>. Development keys begin
        thr_dev_; Production keys begin thr_prod_. Each key is scoped to a
        workspace and environment. Keep secrets on your server.

````

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