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

# Get observations

> List observations recorded after `since` for up to 100 company domains, oldest first, with an opaque cursor for further pages. Reads the existing dataset only; no provider or AI calls run in the request. Domains without coverage are reported as not_found and queued for a scheduled refresh where a permitted source exists. Completed requests consume one request unit and one delivered unit per distinct company; identical retries do not settle again. Current evidence eligibility is rechecked on every read.

Examples use fictional test data and illustrative IDs, dates, and allowances. They are not live prospects or current account balances.



## OpenAPI

````yaml /openapi.json get /api/observations
openapi: 3.1.0
info:
  title: Jolts API
  version: 1.0.0
  description: >-
    Implemented HTTP contract. Authentication uses an account-scoped bearer
    credential. Current coverage is partial; a matching company is not a
    guarantee of buying intent.


    Response examples use fictional test companies and illustrative IDs, dates
    and allowances. They are not live customer results or evidence of market
    coverage.
servers:
  - url: https://app.jolts.xyz
    description: Application API
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Find prospects and investigate their supporting evidence.
  - name: Observations
    description: Search individual company activities and inspect their sources.
  - name: Operations
    description: Start background work and retrieve its results.
  - name: Account
    description: Check your subscription and shared usage allowance.
paths:
  /api/observations:
    get:
      tags:
        - Companies
      summary: Get observations
      description: >-
        List observations recorded after `since` for up to 100 company domains,
        oldest first, with an opaque cursor for further pages. Reads the
        existing dataset only; no provider or AI calls run in the request.
        Domains without coverage are reported as not_found and queued for a
        scheduled refresh where a permitted source exists. Completed requests
        consume one request unit and one delivered unit per distinct company;
        identical retries do not settle again. Current evidence eligibility is
        rechecked on every read.


        Examples use fictional test data and illustrative IDs, dates, and
        allowances. They are not live prospects or current account balances.
      operationId: getObservations
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Unique operation key. Reuse only for identical retries, including
            across HTTP/MCP. Each new page needs a new key.
        - name: domains[]
          in: query
          required: true
          style: form
          explode: true
          description: Company domains, repeated.
          schema:
            type: array
            minItems: 1
            maxItems: 100
            items:
              type: string
        - name: since
          in: query
          required: true
          description: ISO 8601 time; only observations recorded after it are returned.
          schema:
            type: string
            format: date-time
        - name: kinds[]
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - procurement_request
                - facility_expansion
                - funding_round
                - leadership_change
                - product_launch
                - partnership
                - technology_use
                - job_posting
                - company_profile
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: >-
            Observations recorded after the requested time for the requested
            domains.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationLookupResult'
              examples:
                observations:
                  $ref: '#/components/examples/getObservations200'
        '202':
          description: Pending or processing; poll the returned usage ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pending'
              examples:
                pending:
                  $ref: '#/components/examples/searchCompanies202'
        '401':
          description: Missing or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidCredential'
        '402':
          description: An active or trialing subscription is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/subscriptionRequired'
        '422':
          description: >-
            Invalid request, conflicting retry, expired operation or processing
            failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_lookup:
                  $ref: '#/components/examples/invalidLookup'
        '429':
          description: Subscription request or delivery allowance reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/requestLimit'
components:
  schemas:
    ObservationLookupResult:
      type: object
      additionalProperties: false
      required:
        - usage
        - request_allowance
        - observations
        - domains
        - as_of
        - next_cursor
        - coverage_status
        - limitations
        - delivery_unit
        - withheld_units
      properties:
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
        observations:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/Observation'
          description: >-
            Observations recorded after `since` for the requested domains,
            oldest first. Each is a dated fact with evidence, not a verified
            buying decision.
        domains:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required:
              - hostname
              - status
            properties:
              hostname:
                type: string
              status:
                type: string
                enum:
                  - found
                  - not_found
          description: >-
            Each normalized requested domain and whether the dataset currently
            knows a company for it. not_found means no coverage yet, not that
            the company is inactive.
        as_of:
          type: string
          format: date-time
        next_cursor:
          type:
            - string
            - 'null'
        coverage_status:
          const: partial
          type: string
        limitations:
          type: array
          items:
            type: string
        delivery_unit:
          type: string
          const: company
        withheld_units:
          type: integer
          minimum: 0
    Pending:
      type: object
      examples:
        - usage:
            id: 789
            status: pending
            request_key: first-company-search
            request_units: 0
            delivered_units: 0
            fresh_evidence_units: 0
          request_allowance:
            window_seconds: 18000
            window_remaining: 99
            weekly_remaining: 499
      properties:
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - usage
        - request_allowance
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retry_at:
              type: string
              format: date-time
              description: >-
                Advisory retry time for the reached capacity limit, based on
                usage at rejection. Other requests or completing reservations
                may change availability.
            retry_after_seconds:
              type: integer
              minimum: 0
              description: >-
                Seconds from rejection to retry_at. For stored failed
                operations, prefer the absolute retry_at timestamp.
          required:
            - code
            - message
          additionalProperties: false
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - error
      additionalProperties: false
    Operation:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - pending
            - processing
            - delivered
            - failed
        request_key:
          type: string
        request_units:
          type: integer
          minimum: 0
        delivered_units:
          type: integer
          minimum: 0
        fresh_evidence_units:
          type: integer
          minimum: 0
      required:
        - id
        - status
        - request_key
        - request_units
        - delivered_units
        - fresh_evidence_units
      additionalProperties: false
    Allowance:
      type: object
      properties:
        window_seconds:
          type: integer
          minimum: 0
        window_remaining:
          type: integer
          minimum: 0
        weekly_remaining:
          type: integer
          minimum: 0
      required:
        - window_seconds
        - window_remaining
        - weekly_remaining
      additionalProperties: false
    Observation:
      type: object
      properties:
        categories:
          $ref: '#/components/schemas/Categories'
        id:
          type: integer
          minimum: 1
        kind:
          type: string
          enum:
            - procurement_request
            - facility_expansion
            - funding_round
            - leadership_change
            - product_launch
            - partnership
            - technology_use
            - job_posting
            - company_profile
        observed_fact:
          type: string
        why_it_may_matter:
          type: string
        demand_class:
          type: string
          enum:
            - explicit_request
            - proxy
            - structural
        country:
          type: string
          enum:
            - CA
            - US
        confidence:
          type: number
          minimum: 0
          maximum: 1
        occurred_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Event time; may be null only for company_profile. Structural fit is
            not evidence of current buying intent.
        observed_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/Evidence'
        company:
          $ref: '#/components/schemas/CompanyIdentity'
      required:
        - id
        - kind
        - observed_fact
        - why_it_may_matter
        - demand_class
        - country
        - confidence
        - occurred_at
        - observed_at
        - expires_at
        - evidence
        - company
      additionalProperties: false
    Categories:
      type: array
      maxItems: 100
      description: >-
        Source-reported NAICS 2022 sector codes; industry classification, not
        products or buying intent.
      items:
        type: string
        enum:
          - '11'
          - '21'
          - '22'
          - '23'
          - 31-33
          - '42'
          - 44-45
          - 48-49
          - '51'
          - '52'
          - '53'
          - '54'
          - '55'
          - '56'
          - '61'
          - '62'
          - '71'
          - '72'
          - '81'
          - '92'
    Evidence:
      type: object
      properties:
        source_uri:
          type: string
          description: >-
            Source reference supplied with the evidence. For company profiles
            this may be a company homepage, not the origin of each profile field
            or an independently verified citation.
        excerpt:
          type: string
          description: >-
            Retained supporting text. For company profiles this is a
            provider-reported description, not necessarily a quotation from
            source_uri.
        occurred_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Source event time, or null for a structural company profile with no
            reported event date.
        last_seen_at:
          type: string
          format: date-time
          description: >-
            Latest retrieval of this unchanged source record; not a new event or
            independent verification.
        observed_at:
          type: string
          format: date-time
      required:
        - source_uri
        - excerpt
        - occurred_at
        - observed_at
      additionalProperties: false
    CompanyIdentity:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
      required:
        - id
        - name
      additionalProperties: false
  examples:
    getObservations200:
      summary: One new observation for a requested domain (fictional)
      value:
        as_of: '2026-09-25T12:00:00Z'
        coverage_status: partial
        limitations:
          - limited_source_coverage
          - dataset_read_only
        next_cursor: null
        usage:
          id: 981239950
          status: delivered
          request_key: observations-2026-09-25
          request_units: 1
          delivered_units: 1
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 197
          weekly_remaining: 997
        delivery_unit: company
        withheld_units: 0
        observations:
          - id: 23
            kind: procurement_request
            observed_fact: Issued a request for fleet charging equipment at a new depot.
            why_it_may_matter: >-
              This observed company activity may be relevant to the search
              objective; verify fit against the evidence.
            demand_class: explicit_request
            country: US
            confidence: 1
            occurred_at: '2026-09-18T00:00:00Z'
            observed_at: '2026-09-25T02:47:06Z'
            expires_at: null
            evidence:
              - source_uri: https://sequoia.example.test/tenders/fleet-charging
                excerpt: Issued a request for fleet charging equipment at a new depot.
                occurred_at: '2026-09-18T00:00:00Z'
                observed_at: '2026-09-25T02:47:06Z'
                last_seen_at: '2026-09-25T02:47:06Z'
            company:
              id: 23
              name: Sequoia Freight
            categories: []
        domains:
          - hostname: sequoia.example.test
            status: found
          - hostname: absent.example.test
            status: not_found
    searchCompanies202:
      summary: Accepted; poll usage.id
      value:
        usage:
          id: 981239949
          status: pending
          request_key: company
          request_units: 0
          delivered_units: 0
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 198
          weekly_remaining: 998
    invalidCredential:
      summary: invalid_api_key
      value:
        error:
          code: invalid_api_key
          message: Provide a valid API credential.
    subscriptionRequired:
      summary: subscription_required
      value:
        error:
          code: subscription_required
          message: An active or trialing subscription is required.
    invalidLookup:
      summary: No lookup identifiers supplied
      value:
        error:
          code: invalid_lookup
          message: Supply either ids or domains, without other parameters
    requestLimit:
      summary: Request allowance reached (illustrative retry time)
      value:
        error:
          code: request_limit_reached
          message: The subscription request limit has been reached.
          retry_at: '2026-09-25T05:00:00Z'
          retry_after_seconds: 60
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````