---
openapi: 3.0.0
info:
  title: Meta AI API
  description: Get Meta AI answers as structured JSON. To continue an answer, pass
    pagination.conversation_token with the next question. Keep the same country and
    omit lat and lon for follow-up requests. Use lat and lon together when starting
    a location-based conversation. Answers use the country’s default time zone or
    the nearest time zone to the supplied coordinates, and retain it on follow-ups.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Meta AI Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to meta_ai.
        schema:
          type: string
          enum:
          - meta_ai
      - name: q
        in: query
        required: true
        description: The question to send to Meta AI, up to 15000 characters. The
          limit counts UTF-16 code units; a supplementary character such as an emoji
          counts as two.
        schema:
          type: string
          maxLength: 15000
      - name: country
        in: query
        required: false
        description: The country for the answer. Keep the same country when continuing
          a conversation.
        schema:
          type: string
          enum:
          - us
          - gb
          - de
          - uk
          - ar
          - bd
          - br
          - ca
          - eg
          - es
          - fr
          - id
          - in
          - it
          - kr
          - mx
          - ng
          - ph
          - pk
          - pl
          - th
          - tr
          - vn
          default: us
      - name: lat
        in: query
        required: false
        description: 'The latitude for a new conversation. Supply lat and lon together
          and omit them on follow-ups. Valid range: -90 to 90.'
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: false
        description: 'The longitude for a new conversation. Supply lat and lon together
          and omit them on follow-ups. Valid range: -180 to 180.'
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: conversation_token
        in: query
        required: false
        description: Use pagination.conversation_token from a fresh response to continue
          the conversation.
        schema:
          type: string
          maxLength: 4096
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with query parameters,
            such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been
            exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchMetadata:
      type: object
      required:
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Upstream URL used for this search
        html_url:
          type: string
          description: URL to view the stored response as escaped JSON
        json_url:
          type: string
          description: URL to view JSON results
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    SearchResponse:
      type: object
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        text_blocks:
          type: array
          description: The answer split into structured blocks.
          items:
            "$ref": "#/components/schemas/AiAnswerTextBlock"
        markdown:
          type: string
          description: The answer in Markdown.
        reference_links:
          type: array
          description: The sources cited by the answer.
          items:
            type: object
            properties:
              index:
                type: integer
                description: Zero-based position of this reference in `reference_links`
              title:
                type: string
                description: Page title
              link:
                type: string
                description: URL of the reference
              source:
                type: string
                description: Source website name
              favicon:
                type: string
                description: Favicon URL of the source
              snippet:
                type: string
                description: Text snippet from the referenced page
            additionalProperties: false
        web_results:
          type: array
          description: The pages retrieved for the answer.
          items:
            type: object
            properties:
              position:
                type: integer
                description: The position in the result collection.
              title:
                type: string
                description: Page title.
              link:
                type: string
                description: The destination URL.
              source:
                type: string
                description: Website name.
              favicon:
                type: string
                description: Favicon URL of the website.
              snippet:
                type: string
                description: Excerpts of the page from Meta AI's web search, as plain
                  text that keeps its line breaks.
            additionalProperties: false
        map_image:
          type: string
          description: URL of the map showing locations from the answer.
        cards:
          type: array
          description: The social media profiles the answer names.
          items:
            oneOf:
            - type: object
              properties:
                type:
                  type: string
                  description: The card kind.
                  enum:
                  - knowledge_entity
                name:
                  type: string
                  description: Full name shown on the profile.
                category:
                  type: string
                  description: Type of profile as Meta AI labels it, in lowercase.
                id:
                  type: string
                  description: Meta AI's identifier for the profile.
                details:
                  type: object
                  description: The profile's link, username, picture and verification
                    status.
                  properties:
                    link:
                      type: string
                      description: The destination URL.
                    username:
                      type: string
                      description: Username of the profile.
                    avatar:
                      type: string
                      description: URL of the profile picture.
                    is_verified:
                      type: boolean
                      description: Whether the profile is verified.
                  additionalProperties: false
              additionalProperties: false
              required:
              - type
        thinking_steps:
          type: array
          description: The reasoning Meta AI showed before the answer.
          items:
            type: object
            properties:
              title:
                type: string
                description: Heading of the reasoning step.
              description:
                type: string
                description: Meta AI's explanation of what it does in the reasoning
                  step.
            additionalProperties: false
        response_metadata:
          type: object
          description: Details about the answer.
          properties:
            message_id:
              type: string
              description: Meta AI's identifier for the answer.
            title:
              type: string
              description: The title Meta AI gave the conversation.
            is_web_search_performed:
              type: boolean
              description: Whether Meta AI ran a search for the answer.
          additionalProperties: false
        search_queries:
          type: array
          description: The searches Meta AI ran for the answer, in the order it ran
            them.
          items:
            type: string
        local_results:
          type: array
          description: The places Meta AI found for the answer.
          items:
            type: object
            properties:
              position:
                type: integer
                description: The position in the result collection.
              title:
                type: string
                description: Place name.
              place_id:
                type: string
                description: Meta AI's identifier for the place.
              address:
                type: string
                description: Address of the place as a single comma-separated line.
              gps_coordinates:
                type: object
                description: GPS coordinates of the place.
                properties:
                  latitude:
                    type: number
                    description: Latitude of the place in decimal degrees.
                  longitude:
                    type: number
                    description: Longitude of the place in decimal degrees.
                additionalProperties: false
              type:
                type: string
                description: Primary category of the place.
              types:
                type: array
                description: Categories of the place, with the primary category first.
                items:
                  type: string
              website:
                type: string
                description: Website URL of the place.
              phone:
                type: string
                description: Phone number of the place.
              price:
                type: string
                description: Price level of the place, as a lowercase label.
              rating:
                type: number
                description: Average rating of the place.
              reviews:
                type: integer
                description: Number of reviews the rating is based on.
              description:
                type: string
                description: Description of the place in its own words.
              open_state:
                type: string
                description: Operating status of the place at the time of the answer.
              open_hours:
                type: array
                description: Opening hours of the place, one entry per day.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Day of the week, in English.
                    value:
                      type: string
                      description: Opening times on that day, with several time ranges
                        separated by commas.
                  additionalProperties: false
              timezone:
                type: string
                description: IANA time zone of the place.
              links:
                type: array
                description: The place's pages on other sites.
                items:
                  type: object
                  description: The destination URL.
                  properties:
                    type:
                      type: string
                      description: Meta AI's label for the site or kind of page the
                        link points to.
                    link:
                      type: string
                      description: The destination URL.
                  additionalProperties: false
            additionalProperties: false
        error:
          type: string
          description: Message saying why Meta AI returned no answer.
        pagination:
          type: object
          description: How to continue the conversation.
          properties:
            conversation_token:
              type: string
              description: The token to pass with the next question.
          additionalProperties: false
      additionalProperties: false
      required:
      - search_metadata
      - search_parameters
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          enum:
          - meta_ai
          description: Set to meta_ai.
        q:
          type: string
          maxLength: 15000
          description: The question to send to Meta AI, up to 15000 characters. The
            limit counts UTF-16 code units; a supplementary character such as an emoji
            counts as two.
        country:
          type: string
          enum:
          - us
          - gb
          - de
          - uk
          - ar
          - bd
          - br
          - ca
          - eg
          - es
          - fr
          - id
          - in
          - it
          - kr
          - mx
          - ng
          - ph
          - pk
          - pl
          - th
          - tr
          - vn
          default: us
          description: The country for the answer. Keep the same country when continuing
            a conversation.
        lat:
          type: string
          description: 'The latitude for a new conversation. Supply lat and lon together
            and omit them on follow-ups. Valid range: -90 to 90.'
        lon:
          type: string
          description: 'The longitude for a new conversation. Supply lat and lon together
            and omit them on follow-ups. Valid range: -180 to 180.'
        conversation_token:
          type: string
          maxLength: 4096
          description: Use pagination.conversation_token from a fresh response to
            continue the conversation.
    AiAnswerTextBlock:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - header
          - paragraph
          - unordered_list
          - ordered_list
          - table
          - code_blocks
          description: Type of content block.
        answer:
          type: string
          description: Text of a header, paragraph or list item, with inline code
            kept in backticks.
        reference_indexes:
          type: array
          description: Zero-based indexes into `reference_links` cited by this block
          items:
            type: integer
        items:
          type: array
          description: Nested blocks within a list or list item.
          items:
            "$ref": "#/components/schemas/AiAnswerTextBlock"
        table:
          type: object
          description: Table data (for table type)
          required:
          - headers
          - rows
          properties:
            headers:
              type: array
              description: Table header row; cells keep inline-code backticks like
                `answer`
              items:
                type: string
            rows:
              type: array
              description: Table data rows; cells keep inline-code backticks like
                `answer`
              items:
                type: array
                items:
                  type: string
        language:
          type: string
          description: Programming language (for code_blocks type)
        code:
          type: string
          description: Code content (for code_blocks type)
