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

# Fetch URL context

> Fetch Markdown, HTML, links, query highlights, and page metadata for a batch of URLs.



## OpenAPI

````yaml post /v1/context
openapi: 3.1.0
info:
  title: Perplexity AI API
  description: Perplexity AI API
  version: 1.0.0
servers:
  - url: https://api.perplexity.ai
    description: Perplexity AI API
security: []
paths:
  /v1/context:
    post:
      tags:
        - Context API
      summary: Fetch URL context
      description: >-
        Fetch Markdown, HTML, links, highlights, and page metadata for 1 to 50
        URLs. The response has one result per input URL, in input order. Check
        each result's status.type for per-URL failures.
      operationId: context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextRequest'
            examples:
              basic:
                summary: Markdown for one URL
                value:
                  urls:
                    - https://info.cern.ch/hypertext/WWW/TheProject.html
              highlights:
                summary: All formats with highlights for a query
                value:
                  urls:
                    - https://info.cern.ch/hypertext/WWW/TheProject.html
                  formats:
                    - markdown
                    - html
                    - links
                    - highlights
                  highlights:
                    query: What is the WorldWideWeb project?
                    max_tokens_per_url: 128
      responses:
        '200':
          description: One document per input URL, in request order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
              example:
                request_id: 275fdeba-bc88-466a-a029-48429cf97ff6
                results:
                  - markdown: >-
                      The World Wide Web project


                      # World Wide Web

                      The WorldWideWeb (W3) is a wide-area hypermedia
                      information retrieval initiative aiming to give universal
                      access to a large universe of documents.


                      Everything there is online about

                      W3 is linked directly or indirectly

                      to this document, including an executive summary of the
                      project, Mailing lists , Policy , November's W3 news ,
                      Frequently Asked Questions .


                      - **What's out there?**
                        Pointers to the world's online information, subjects , W3 servers, etc.
                      - **Help**
                        on the browser you are using
                      - **Software Products**
                        A list of W3 project components and their current state. (e.g. Line Mode ,X11 Viola , NeXTStep , Servers , Tools , Mail robot , Library )
                      - **Technical**
                        Details of protocols, formats, program internals etc
                      - **Bibliography**
                        Paper documentation on W3 and references.
                      - **People**
                        A list of some people involved in the project.
                      - **History**
                        A summary of the history of the project.
                      - **How can I help ?**
                        If you would like to support the web..
                      - **Getting code**
                        Getting the code by anonymous FTP , etc.
                    metadata:
                      content_type: text/html
                      fetched_at: '2026-11-16T23:55:18Z'
                      origin: cached
                      source_url: https://info.cern.ch/hypertext/WWW/TheProject.html
                      title: The World Wide Web project
                    status:
                      status_code: 200
                      type: ok
                    url: https://info.cern.ch/hypertext/WWW/TheProject.html
                usage:
                  cost:
                    currency: USD
                    total_cost: 0.001
                  fetched_urls: 1
        '400':
          description: >-
            Invalid request: malformed JSON, a request body over 512 KiB, a null
            value, a wrong type or out-of-range value, zero URLs or more than 50
            (or more than your usage tier allows), a parameter combination that
            is not allowed, an unknown parameter (unsupported_param), or an
            unknown format (unsupported_format). Fix the request before you send
            it again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: highlights is required when formats has highlights
                  type: invalid_request
                  code: 400
                  param: highlights
                  request_id: 34497711-83fc-4ea3-9e86-ad4d28d68415
        '401':
          description: >-
            The API key is missing, invalid, or expired (invalid_api_key,
            token_expired), or the account has no credit left
            (insufficient_quota).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: >-
                    Invalid API key provided. You can find your API key at
                    https://console.perplexity.ai.
                  type: invalid_api_key
                  code: 401
        '403':
          description: >-
            Access denied. error.type is forbidden, api_product_not_allowed, or
            safety_identifier_blocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: >-
                    Access denied. Your API key does not have permission to
                    access this resource.
                  type: forbidden
                  code: 403
        '405':
          description: >-
            The request used a method other than POST. The response has an
            Allow: POST header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: /v1/context accepts only POST
                  type: invalid_request
                  code: 405
                  request_id: 5c6b20a4-f833-4639-88bf-d2e3929fe74d
        '429':
          description: >-
            Rate limit exceeded (request_rate_limit_exceeded or
            rate_limit_exceeded). Each request counts as one unit against your
            usage tier's requests-per-second limit, whatever its URL count. Wait
            the number of seconds in the Retry-After header, when present,
            before retrying. See [Context API
            limits](/docs/admin/rate-limits-usage-tiers#context-api-limits).
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: Rate limit exceeded, please try again later.
                  type: request_rate_limit_exceeded
                  code: 429
        '500':
          description: Unexpected server error. No results are returned. You can retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: Internal server error
                  type: internal_error
                  code: 500
        '502':
          description: >-
            The request could not be completed (bad_gateway or server_error). No
            results are returned. You can retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: The content service failed to process the request.
                  type: bad_gateway
                  code: 502
        '503':
          description: >-
            The service is temporarily unavailable (server_error). No results
            are returned. You can retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
        '504':
          description: >-
            The request did not complete in time (gateway_timeout or
            timeout_error). No results are returned. You can retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextErrorResponse'
              example:
                error:
                  message: The request did not complete within timeout_ms.
                  type: gateway_timeout
                  code: 504
      security:
        - HTTPBearer: []
components:
  schemas:
    ContextRequest:
      type: object
      additionalProperties: false
      required:
        - urls
      properties:
        urls:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
          description: >-
            1 to 50 http or https URLs. Your usage tier can lower the maximum. A
            string that is not an absolute http or https URL does not fail the
            request: its result has status.type invalid_url.
        formats:
          type: array
          default:
            - markdown
          items:
            type: string
            enum:
              - markdown
              - html
              - links
              - highlights
          description: >-
            What to return besides metadata, which is always returned for a page
            with content. highlights requires the highlights object. [] returns
            metadata only.
        highlights:
          $ref: '#/components/schemas/ContextHighlights'
        if_modified_since:
          type: string
          description: >-
            A metadata.last_modified value from an earlier response, in
            IMF-fixdate form such as Thu, 03 Dec 1992 08:37:20 GMT. Requires
            exactly one URL and max_age_seconds 0. If the page has not changed
            since then, its result has status.type not_modified and no content,
            so keep the content you already have.
        max_age_seconds:
          type: integer
          minimum: 0
          maximum: 63072000
          default: 172800
          description: >-
            Maximum age of a stored copy to accept, up to 63072000 (two years).
            0 always fetches the page live. Cannot be combined with
            snapshot_as_of.
        cache_only:
          type: boolean
          default: false
          description: >-
            When true, answer only from stored copies at most max_age_seconds
            old and never fetch live. A URL without one has status.type
            no_content. Requires max_age_seconds above 0. Cannot be combined
            with snapshot_as_of.
        snapshot_as_of:
          type: string
          description: >-
            Return each URL as stored at or before this RFC 3339 time with a
            time zone, such as 2026-11-01T00:00:00Z. It must not be in the
            future or more than 90 days ago. Never fetches live: a URL with no
            stored copy from before that time has status.type no_content. Cannot
            be combined with max_age_seconds, cache_only, or if_modified_since.
        timeout_ms:
          type: integer
          minimum: 1000
          maximum: 110000
          default: 30000
          description: >-
            Time budget for fetching each URL, in milliseconds. URLs are fetched
            in parallel. A URL not fetched in time has status.type crawl_timeout
            and is not billed.
    ContextResponse:
      type: object
      required:
        - request_id
        - results
        - usage
      properties:
        request_id:
          type: string
          description: >-
            The request ID, the same value as the X-Request-Id response header.
            Include it when you contact support.
        results:
          type: array
          description: One result per input URL, in request order.
          items:
            $ref: '#/components/schemas/ContextDocument'
        usage:
          $ref: '#/components/schemas/ContextUsage'
    ContextErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
          properties:
            message:
              type: string
            type:
              type: string
              enum:
                - invalid_request
                - invalid_api_key
                - insufficient_quota
                - token_expired
                - rate_limit_exceeded
                - unsupported_format
                - unsupported_param
                - forbidden
                - api_product_not_allowed
                - safety_identifier_blocked
                - request_rate_limit_exceeded
                - internal_error
                - bad_gateway
                - server_error
                - gateway_timeout
                - timeout_error
              description: The error type. See each status code for its types.
            code:
              type: integer
              description: HTTP status code
            param:
              type: string
              description: The request field the error is about, when one applies.
            request_id:
              type: string
              description: >-
                The request ID. Present on errors the Context API returns
                itself.
    ContextHighlights:
      type: object
      additionalProperties: false
      required:
        - query
      description: >-
        Highlights settings. Required when formats includes highlights, and
        allowed only then.
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            What to look for in each page, 1 to 1024 characters. It must contain
            a non-whitespace character.
        max_tokens_per_url:
          type: integer
          minimum: 1
          maximum: 4096
          default: 1024
          description: Maximum length of each page's highlights, in tokens.
    ContextDocument:
      type: object
      required:
        - url
        - status
      description: >-
        No field is ever null: a field without a value is omitted. markdown,
        html, links, and highlights appear only when requested and status.type
        is ok. metadata appears when status.type is ok or not_modified. A failed
        result has only url and status.
      properties:
        url:
          type: string
          description: The URL exactly as you sent it.
        markdown:
          type: string
          description: The page content as Markdown.
        html:
          type: string
          description: The page's HTML. Omitted for a page that is not HTML, such as a PDF.
        links:
          type: array
          items:
            type: string
          description: >-
            The page's links as absolute URLs, without duplicates, in page
            order. [] for a page without links.
        highlights:
          type: string
          description: >-
            The passages of the page most relevant to highlights.query, as one
            string of extracted page text. Omitted when no passage matches.
        metadata:
          $ref: '#/components/schemas/ContextMetadata'
        status:
          $ref: '#/components/schemas/ContextStatus'
    ContextUsage:
      type: object
      required:
        - fetched_urls
        - cost
      properties:
        fetched_urls:
          type: integer
          description: >-
            The number of billed URLs: the results whose status.type is ok or
            not_modified. Failed URLs are free, so this is 0 when every URL
            fails.
        cost:
          $ref: '#/components/schemas/ContextCost'
      description: The number of billed URLs in this request and their cost at list price.
    ContextMetadata:
      type: object
      required:
        - source_url
      description: >-
        Returned when status.type is ok or not_modified, whatever formats asks
        for. A field without a value is omitted. Every other meta tag in the
        page's head (name, property, or itemprop) is returned under its
        lowercased name, such as og:title: a string, or an array in page order
        when the page repeats the tag.
      properties:
        source_url:
          type: string
          description: >-
            The URL the content came from, after normalization and redirects. It
            can differ from url.
        title:
          type: string
          description: Page title.
        description:
          type: string
          description: Page description.
        language:
          type: string
          description: Page language, such as en.
        author:
          type: string
          description: Page author.
        published_date:
          type: string
          format: date
          description: Publication date (YYYY-MM-DD).
        content_type:
          type: string
          description: Content-Type reported for the page.
        origin:
          type: string
          enum:
            - cached
            - live
          description: >-
            cached: a stored copy, chosen by max_age_seconds, cache_only, or
            snapshot_as_of. live: fetched for this request.
        fetched_at:
          type: string
          format: date-time
          description: When the returned content was fetched.
        last_modified:
          type: string
          description: >-
            The site's Last-Modified header, when it sent one. Send it as
            if_modified_since to check whether the page changed. It is not a
            publication date or fetch time.
      additionalProperties:
        oneOf:
          - type: string
          - items:
              type: string
            type: array
    ContextStatus:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - ok
            - not_modified
            - invalid_url
            - blocked
            - bot_challenge
            - crawl_failed
            - crawl_timeout
            - no_text
            - no_content
            - internal_error
          description: >-
            ok: content returned. not_modified: unchanged since
            if_modified_since. invalid_url: not an absolute http or https URL.
            blocked: the URL is blocked and was not fetched. bot_challenge: the
            site answered with a bot challenge. crawl_failed: the fetch failed.
            crawl_timeout: fetching the page timed out. no_text: the page has no
            text, and formats has markdown. no_content: no content was found for
            the URL. internal_error: the URL could not be read; retry later.
        status_code:
          type: integer
          description: >-
            The site's own HTTP status, on ok, not_modified, bot_challenge, and
            crawl_failed, when the site answered.
        message:
          type: string
          description: A fixed sentence describing the failure. Only on failures.
      description: What happened to this URL.
    ContextCost:
      type: object
      required:
        - total_cost
        - currency
      description: The cost of the request at list price. It is not the amount charged.
      properties:
        total_cost:
          type: number
          format: double
          description: >-
            fetched_urls multiplied by the list price per URL. See [Context API
            pricing](/docs/getting-started/pricing#context-api-pricing).
        currency:
          $ref: '#/components/schemas/ContextCurrency'
    ContextCurrency:
      type: string
      description: The currency of total_cost. Always USD.
      enum:
        - USD
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````