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

# Airsearch

> Research the web and return structured answers with Airsearch. Rate limit: 300 requests per minute per workspace.

Ask a research question and receive a sourced answer, with optional output fields shaped for your application.

<Note>
  The limit is 300 requests per minute per workspace. A `success` result costs 1 credit; `not_found` and `timeout` are not charged. Credits reserved for a completed `not_found` or `timeout` result are returned.
</Note>

Requested schema keys are optional and nullable. Structured numeric and boolean values are returned as strings when present, so parse them explicitly when your application requires native scalar types.

A timeout can return `200 OK` with `status: "timeout"` or `504 Gateway Timeout`. Narrow the prompt before retrying. For temporary `502` or `503` errors, retry with increasing delays and a fixed retry limit; contact support if errors persist.

## Next step

Use [Find companies](/api-reference/find-companies) when the research target should come from structured firmographic filters, or review [Rate limits](/api-reference/rate-limits) before adding parallel requests.


## OpenAPI

````yaml openapi.json POST /v1/airsearch
openapi: 3.1.0
info:
  title: Airscale Public API
  version: '2026-09-11'
  description: Search, enrich, and resolve public business data with Airscale.
  x-airscale-source-repository: ViceScale/airscale-code
  x-airscale-source-sha: 1de19e1b70a052a4b8d9c2075021a7e5e7a94d51
servers:
  - url: https://api.airscale.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search and discovery
    description: Search people, companies, and the web.
  - name: Contact data
    description: Find professional and personal contact data.
  - name: Profiles and reverse lookup
    description: Extract profiles or resolve a person from known contact data.
  - name: Post engagement
    description: Retrieve and enrich people who liked or commented on LinkedIn posts.
  - name: LinkedIn content
    description: >-
      Search LinkedIn posts, read profile and company feeds, and retrieve
      profile comments and comment reactions.
  - name: Account
    description: Inspect workspace account state.
  - name: Miscellaneous
    description: Check WhatsApp availability, Meta ads, and email deliverability.
paths:
  /v1/airsearch:
    post:
      tags:
        - Search and discovery
      summary: Research the web with Airsearch
      description: >-
        Researches a public question and returns a sourced answer with optional
        requested output fields. The JSON request body is limited to 256 KiB.
      operationId: airsearch
      requestBody:
        required: true
        description: >-
          Provide a non-empty prompt and, optionally, a map of requested output
          names to type keywords or descriptions.
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              additionalProperties: false
              properties:
                prompt:
                  type: string
                  minLength: 1
                  pattern: \S
                  description: >-
                    A research question or instruction that remains non-empty
                    after surrounding whitespace is trimmed.
                schema:
                  type: object
                  propertyNames:
                    minLength: 1
                    pattern: \S
                    not:
                      enum:
                        - status
                        - response
                        - reasoning
                        - sources
                        - confidence_score
                        - certainty_tag
                        - duration_ms
                  additionalProperties:
                    type: string
                    minLength: 1
                    pattern: \S
                  description: >-
                    Maps arbitrary requested output names to non-empty type
                    keywords or plain-language descriptions. Stable envelope
                    names are reserved because dynamic requested fields must not
                    collide with status, response, reasoning, sources,
                    confidence_score, certainty_tag, or duration_ms.
            examples:
              structuredResearch:
                summary: Research a synthetic company
                value:
                  prompt: >-
                    What category does Example Company use to describe its
                    service at https://example.com?
                  schema:
                    category: string
      responses:
        '200':
          description: >-
            A completed research result, including successful, not-found, and
            soft-timeout outcomes.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - response
                  - reasoning
                  - sources
                  - confidence_score
                  - certainty_tag
                  - duration_ms
                properties:
                  status:
                    $ref: '#/components/schemas/Status'
                  response:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                  reasoning:
                    type:
                      - string
                      - 'null'
                  sources:
                    type: array
                    items:
                      type: string
                      description: >-
                        A public source URL, public source label such as
                        serp_snippets, or an empty string forwarded from the
                        upstream result.
                  confidence_score:
                    type: number
                    minimum: 0
                    maximum: 1
                  certainty_tag:
                    type:
                      - string
                      - 'null'
                    enum:
                      - low
                      - medium
                      - high
                      - null
                    description: Null when no certainty tag could be derived.
                  duration_ms:
                    type: number
                    minimum: 0
                additionalProperties:
                  type:
                    - string
                    - 'null'
              examples:
                success:
                  summary: Synthetic successful research
                  value:
                    status: success
                    response: >-
                      Example Company describes its service as workflow
                      automation.
                    category: workflow automation
                    reasoning: The public example page and search snippets agree.
                    sources:
                      - https://example.com
                      - serp_snippets
                    confidence_score: 0.92
                    certainty_tag: high
                    duration_ms: 8420
                notFound:
                  summary: No usable result
                  value:
                    status: not_found
                    response: No relevant information found.
                    category: null
                    reasoning: null
                    sources: []
                    confidence_score: 0.1
                    certainty_tag: low
                    duration_ms: 6900
                timeout:
                  summary: Soft timeout
                  value:
                    status: timeout
                    response: No relevant information found.
                    category: null
                    reasoning: null
                    sources: []
                    confidence_score: 0
                    certainty_tag: low
                    duration_ms: 150000
        '400':
          description: The request is invalid or contains an unsupported field or value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The workspace cannot complete this request because access or
            available credits are insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The JSON request body exceeds the 256 KiB limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            The workspace rate limit has been exceeded. Try again after the
            current window resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            The request could not be completed because of an unexpected server
            error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            The request could not be completed because a required service
            returned an unsuccessful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The request is temporarily unavailable. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: >-
            The initial research stage exceeded its time limit. Narrow the
            prompt before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Status:
      type: string
      enum:
        - success
        - not_found
        - timeout
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: The Bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Use an Airscale workspace API key. Never expose the key in client-side
        code.

````

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