> ## 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 operation > Account-scoped, unmetered polling or replay. Rechecks current evidence and subscription. No new external work. 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/usages/{id} 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/usages/{id}: get: tags: - Operations summary: Get operation description: >- Account-scoped, unmetered polling or replay. Rechecks current evidence and subscription. No new external work. Examples use fictional test data and illustrative IDs, dates, and allowances. They are not live prospects or current account balances. operationId: getUsage parameters: - name: id in: path required: true schema: type: integer minimum: 1 responses: '200': description: Completed company, observation or MCP diagnostic operation. content: application/json: schema: anyOf: - $ref: '#/components/schemas/CompanyResult' - $ref: '#/components/schemas/ObservationResult' - $ref: '#/components/schemas/DiagnosticResult' - $ref: '#/components/schemas/CompanyLookupResult' - $ref: '#/components/schemas/ObservationLookupResult' examples: result: $ref: '#/components/examples/getUsage200' '202': description: Pending or processing. 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' '404': description: Operation not in this account. content: application/json: schema: $ref: '#/components/schemas/Error' examples: error: $ref: '#/components/examples/usageMissing' '422': description: >- Invalid request, conflicting retry, expired operation or processing failure. content: application/json: schema: $ref: '#/components/schemas/Error' examples: error: $ref: '#/components/examples/failedUsage' '429': description: Subscription request or delivery allowance reached. content: application/json: schema: $ref: '#/components/schemas/Error' examples: error: $ref: '#/components/examples/requestLimit' components: schemas: CompanyResult: type: object properties: usage: $ref: '#/components/schemas/Operation' request_allowance: $ref: '#/components/schemas/Allowance' coverage_status: const: partial type: string retrieval: type: string enum: - lexical - hybrid as_of: type: string format: date-time next_cursor: type: - string - 'null' withheld_units: type: integer minimum: 0 delivery_unit: type: string enum: - company - observation companies: type: array items: $ref: '#/components/schemas/CompanyMatch' ranking: type: string const: query_relevance_baseline candidate_limit: type: integer minimum: 100 maximum: 2000 description: >- Candidate scan cap before relevance filtering: max(100, 2 * target), or 100 when target is omitted. The accepted list is capped separately by target. Not a total-market count. coverage: type: object properties: requested_companies: type: integer minimum: 0 description: Requested page size. target_companies: type: integer minimum: 1 maximum: 1000 description: >- Bounded acquisition goal: target when supplied, otherwise the page limit. May be omitted when replaying a search completed before this field was introduced. available_companies: type: integer minimum: 0 maximum: 1000 description: >- Company count in the frozen shortlist. Not a total-market count or a guarantee all remain eligible; evidence withdrawal can shorten subsequent pages. Without an explicit target this can exceed target_companies. May be omitted when replaying a search completed before this field was introduced. returned_companies: type: integer minimum: 0 occurred_after: type: - string - 'null' format: date-time description: >- Effective event-date cutoff, or null for structural company-profile searches. Dated activity searches default to 30 days ago at midnight UTC. stop_reason: type: string limitations: type: array items: type: string required: - requested_companies - returned_companies - stop_reason - limitations additionalProperties: false required: - usage - request_allowance - coverage_status - retrieval - as_of - next_cursor - withheld_units - delivery_unit - companies - ranking - candidate_limit - coverage additionalProperties: false ObservationResult: type: object properties: usage: $ref: '#/components/schemas/Operation' request_allowance: $ref: '#/components/schemas/Allowance' coverage_status: const: partial type: string retrieval: type: string enum: - lexical - hybrid as_of: type: string format: date-time next_cursor: type: - string - 'null' withheld_units: type: integer minimum: 0 delivery_unit: type: string enum: - company - observation observations: type: array items: $ref: '#/components/schemas/Observation' required: - usage - request_allowance - coverage_status - retrieval - as_of - next_cursor - withheld_units - delivery_unit - observations additionalProperties: false DiagnosticResult: type: object additionalProperties: false required: - status - subscription - usage - request_allowance properties: status: const: ok subscription: type: object additionalProperties: false required: - plan - status properties: plan: type: string status: type: string usage: $ref: '#/components/schemas/Operation' request_allowance: $ref: '#/components/schemas/Allowance' CompanyLookupResult: type: object additionalProperties: false required: - usage - request_allowance - companies - lookups - as_of - coverage_status - limitations - delivery_unit - withheld_units properties: usage: $ref: '#/components/schemas/Operation' request_allowance: $ref: '#/components/schemas/Allowance' companies: type: array maxItems: 20 items: type: object properties: id: type: integer minimum: 1 name: type: string domains: type: array items: type: object properties: id: type: integer minimum: 1 hostname: type: string required: - id - hostname additionalProperties: false observations: type: array items: $ref: '#/components/schemas/SupportingObservation' maxItems: 3 limitations: type: array items: type: string required: - id - name - domains - observations - limitations additionalProperties: false lookups: type: array minItems: 1 maxItems: 20 items: type: object additionalProperties: false required: - status properties: id: type: integer minimum: 1 domain: type: string company_id: type: integer minimum: 1 status: type: string enum: - found - not_found - ambiguous - unavailable oneOf: - required: - id - required: - domain allOf: - if: properties: status: const: found then: required: - company_id else: not: required: - company_id as_of: type: string format: date-time coverage_status: const: partial type: string limitations: type: array items: type: string delivery_unit: type: string const: company withheld_units: type: integer minimum: 0 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 CompanyMatch: type: object properties: id: type: integer minimum: 1 name: type: string domains: type: array description: >- Current website domains supported by the returned observations; not every domain associated with the company. items: type: object properties: id: type: integer minimum: 1 hostname: type: string required: - id - hostname additionalProperties: false limitations: type: array items: type: string demand_class: type: string enum: - explicit_request - proxy - structural why_it_may_matter: type: string match: type: object properties: query: type: string observation_ids: type: array items: type: integer minimum: 1 required: - query - observation_ids additionalProperties: false observations: type: array items: $ref: '#/components/schemas/SupportingObservation' maxItems: 3 required: - id - name - limitations - demand_class - why_it_may_matter - match - domains - observations 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 SupportingObservation: type: object description: >- One activity and its supporting sources. The example is fictional, not a live company result. examples: - id: 456 kind: facility_expansion observed_fact: Example Logistics announced a new distribution warehouse. why_it_may_matter: >- A new warehouse may need handling equipment; no purchasing decision is confirmed. demand_class: proxy country: CA confidence: 0.8 occurred_at: '2026-09-20T00:00:00Z' observed_at: '2026-09-21T12:00:00Z' expires_at: null evidence: - source_uri: https://logistics.example/news/warehouse excerpt: We are opening a new distribution warehouse. occurred_at: '2026-09-20T00:00:00Z' observed_at: '2026-09-21T12:00:00Z' 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' required: - id - kind - observed_fact - why_it_may_matter - demand_class - country - confidence - occurred_at - observed_at - expires_at - evidence 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: getUsage200: summary: Illustrative result (fictional test data) value: as_of: '2026-09-25T02:47:07.454303Z' ranking: query_relevance_baseline coverage: limitations: - limited_source_coverage - relevance_not_validated stop_reason: sources_exhausted returned_companies: 2 requested_companies: 10 target_companies: 10 available_companies: 2 retrieval: lexical next_cursor: null delivery_unit: company candidate_limit: 100 coverage_status: partial usage: id: 981239949 status: delivered request_key: company request_units: 1 delivered_units: 2 fresh_evidence_units: 0 request_allowance: window_seconds: 10800 window_remaining: 198 weekly_remaining: 998 companies: - id: 23 name: Sequoia Freight domains: - id: 23 hostname: sequoia.example.test limitations: - limited_source_coverage demand_class: explicit_request why_it_may_matter: >- A stated buying action may relate to "charging"; verify requirements and timing against the cited evidence. match: query: charging observation_ids: - 23 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' - id: 22 name: Northstar Transit domains: - id: 22 hostname: northstar.example.test limitations: - limited_source_coverage demand_class: explicit_request why_it_may_matter: >- A stated buying action may relate to "charging"; verify requirements and timing against the cited evidence. match: query: charging observation_ids: - 22 observations: - id: 22 kind: procurement_request observed_fact: Issued a request for depot charging equipment. 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: CA confidence: 1 occurred_at: '2026-09-04T00:00:00Z' observed_at: '2026-09-25T02:47:06Z' expires_at: null evidence: - source_uri: https://northstar.example.test/tenders/depot-charging excerpt: Issued a request for depot charging equipment. occurred_at: '2026-09-04T00:00:00Z' observed_at: '2026-09-25T02:47:06Z' withheld_units: 0 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. usageMissing: summary: usage_not_found value: error: code: usage_not_found message: No usage has that ID. failedUsage: summary: usage_expired value: error: code: usage_expired message: The request expired. Submit a new request key. 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.