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

# Answer a Research Task

> Research the live web and return structured answers with source URLs. Choose Fast for quick lookups or Ultra for deeper research.

<Badge color="blue">Fast: 10 Credits · Ultra: 100 Credits</Badge>

Describe what you need to find in `task`. Answers searches the web, reads relevant pages, and returns `json_content` in your requested shape, along with the `sources` used.

## Choose a mode

| Mode    | Credits per successful request | Research limit | Use for                                                               |
| ------- | -----------------------------: | -------------- | --------------------------------------------------------------------- |
| `fast`  |                             10 | 30 seconds     | Quick factual lookups and focused questions.                          |
| `ultra` |                            100 | 50 seconds     | Questions that need deeper research, comparisons, or several sources. |

The default is `ultra`. Set `mode` in the JSON request body to select a level.

Successful responses consume the selected mode's credits, including answers with unknown values. Validation, research, and timeout failures are not charged. The `X-Credits-Used` response header reports the charge.

## Shape the answer

Pass `json_format` as an example object. Its keys and placeholder values describe the answer you want. For example, use this request body to find a company's pricing page and plan names:

```json theme={null}
{
  "mode": "fast",
  "task": "Find the pricing page URL and plan names for context.dev.",
  "json_format": {
    "pricing_page_url": "",
    "plans": [{ "name": "" }]
  }
}
```

The response puts the requested fields inside `json_content` and returns source URLs separately:

```json theme={null}
{
  "json_content": {
    "pricing_page_url": "https://www.context.dev/pricing",
    "plans": [
      { "name": "Developer" },
      { "name": "Pro" },
      { "name": "Scale" }
    ]
  },
  "sources": ["https://www.context.dev/pricing"]
}
```

When you omit `json_format`, the answer uses `{"result": ""}`. Nonempty objects preserve their keys. Text, numbers, and `true`/`false` values preserve their types. Unknown values may be `null`. An example array describes the shape of its items; the returned array can contain any number of matching items.

Empty objects accept arbitrary fields, empty arrays accept any JSON items, and a `null` placeholder accepts any JSON value. The example supports at most 8 levels, 500 values, and 16,000 serialized characters. Use an example object rather than a JSON Schema definition.

## Sources and research scope

Include a domain or complete page URL in `task` to focus research on that site. The task can contain up to 2,000 characters after trimming.

`sources` contains the URLs that supplied search results or readable page content, deduplicated in first-seen order. It does not map individual fields to citations. A listed URL may have contributed a search snippet without its full page being read. Page reads contribute a source only when they return readable content.

## Timeouts and errors

Set `timeoutOpts.behavior` to `"return-partial"` to stop research before the deadline and return an answer from the evidence already gathered. A successful partial answer still matches `json_format`, includes `partial: true`, and costs the selected mode's credits. If usable evidence or a valid answer is unavailable, the request fails without a charge. The default behavior is `"fail"`; see [Timeouts and partial results](/optimization/timeouts).

`timeoutOpts.milliseconds` accepts 1,000–300,000 milliseconds. A value below the selected mode's research limit shortens the deadline; a larger value keeps the 30-second Fast or 50-second Ultra limit.

| Status | Meaning                                                                                    |
| ------ | ------------------------------------------------------------------------------------------ |
| `400`  | Invalid input, an unsupported example shape, or a zero data retention request.             |
| `408`  | The caller's deadline expired without a usable partial answer, or with `behavior: "fail"`. |
| `502`  | Research could not gather usable evidence or produce the requested JSON answer.            |
| `504`  | The research or model time limit expired.                                                  |

[Zero data retention](/optimization/zero-data-retention) is unsupported for Answers. Enabling it returns `400 ZDR_NOT_SUPPORTED` before research and billing. Standard authentication and rate limits also apply.


## OpenAPI

````yaml POST /web/answers
openapi: 3.1.0
info:
  title: Context.dev API
  description: API for retrieving context data from any website
  version: 1.0.0
servers:
  - url: https://api.context.dev/v1
security: []
tags:
  - name: Webhooks
    description: Inspect and retry webhook deliveries. These endpoints cost no credits.
  - name: Logs
    description: >-
      Read your organization's API request logs to debug failed calls. These
      endpoints cost no credits and use a separate rate limit.
  - name: Batch
    description: Scrape many pages or crawl a site asynchronously.
  - name: Monitors
    description: >-
      Monitor pages, sitemaps, and extracted website data for exact or semantic
      changes. Webhook payloads are documented by the
      MonitorsChangeDetectedWebhookPayload and
      MonitorsRunCompletedWebhookPayload schemas.
  - name: News
    description: >-
      Search live first-party RSS and free historical news data by company
      identity.
  - name: Answers
    description: Answer a research task from the live web in the JSON shape you ask for.
paths:
  /web/answers:
    post:
      tags:
        - Answers
      summary: Answer a research task from the live web
      description: >-
        Researches the live web and returns a sourced answer in your requested
        JSON shape. Select fast for a smaller research budget at 10 credits or
        ultra for deeper reasoning at 100 credits. Defaults to ultra. Fast
        research is limited to 30 seconds and ultra to 50 seconds;
        timeoutOpts.milliseconds can shorten either deadline.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswersRequest'
            examples:
              fast:
                summary: 'Fast: 10 credits'
                value:
                  mode: fast
                  task: Find the pricing page URL and plan names for context.dev.
                  json_format:
                    pricing_page_url: ''
                    plans:
                      - name: ''
              ultra:
                summary: 'Ultra: 100 credits'
                value:
                  mode: ultra
                  task: >-
                    Compare the monthly pricing and included credits for the
                    plans on context.dev.
                  json_format:
                    plans:
                      - name: ''
                        monthly_price_usd: 0
                        included_credits: 0
                        pricing_page_url: ''
      responses:
        '200':
          description: The requested JSON shape, plus the sources used
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  partial:
                    type: boolean
                    description: >-
                      True when the request deadline ended research and the
                      answer uses the evidence collected so far.
                  json_content:
                    type: object
                    additionalProperties: {}
                    description: The answer, in the shape requested by json_format.
                  sources:
                    type: array
                    items:
                      type: string
                    description: >-
                      URLs that supplied search results or readable page
                      content, in first-seen order. Unreadable pages are
                      excluded.
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                required:
                  - json_content
                  - sources
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '408':
          description: The request exceeded timeoutOpts.milliseconds.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Request exceeded the applicable rate limit.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            Research could not gather usable evidence or produce the requested
            JSON answer.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: The research or model provider exceeded its time limit.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    AnswersRequest:
      type: object
      properties:
        mode:
          type: string
          enum:
            - fast
            - ultra
          description: >-
            Research level: fast uses a smaller model and research budget for 10
            credits; ultra uses deeper reasoning and research for 100 credits.
            Defaults to ultra. Only successful requests consume credits.
        task:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            What to research and answer, in plain language. Naming a domain in
            the task (for example "pricing on context.dev") makes the agent read
            that site before it searches.
        json_format:
          type: object
          additionalProperties: {}
          description: >-
            An example object with placeholder values (for example
            {"pricing_page_url": "", "plans": [{"name": "", "price": 0}]}).
            Object keys and value types are preserved; unknown values may be
            null. Empty arrays accept any JSON items. Defaults to {"result":
            ""}. Maximum 8 levels, 500 values, and 16000 characters.
        timeoutOpts:
          $ref: '#/components/schemas/PartialTimeout'
        tags:
          $ref: '#/components/schemas/RequestTags'
      required:
        - task
      additionalProperties: false
    KeyMetadata:
      type: object
      properties:
        credits_consumed:
          type: integer
          description: Credits used by this request.
        credits_remaining:
          type: integer
          description: Credits remaining for your organization.
      required:
        - credits_consumed
        - credits_remaining
      description: Credit usage, included whenever a valid API key is provided.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        error_code:
          type: string
          enum:
            - INTERNAL_ERROR
            - VALID
            - NOT_FOUND
            - FORBIDDEN
            - USAGE_EXCEEDED
            - RATE_LIMITED
            - UNAUTHORIZED
            - DISABLED
            - PAID_PLAN_REQUIRED
            - INSUFFICIENT_PERMISSIONS
            - TIMEOUT_EXCEEDS_MAXIMUM
            - TIMEOUT_TOO_SHORT_FOR_WAIT
            - WEBSITE_ACCESS_ERROR
            - WEBSITE_BLOCKED
            - WEBSITE_NOT_FOUND
            - PDF_SKIPPED
            - PDF_IMAGES_ONLY
            - EXTERNAL_PROVIDER_ERROR
            - INPUT_VALIDATION_ERROR
            - ZDR_NOT_SUPPORTED
            - ZDR_NOT_ENABLED
            - FREE_EMAIL_DETECTED
            - DISPOSABLE_EMAIL_DETECTED
            - REQUEST_TIMEOUT
            - COLD_DOMAIN_TIMEOUT_TOO_LOW
            - UNSUPPORTED_CONTENT
            - CONTENT_TOO_LARGE
            - MONITOR_PAUSED
            - MONITOR_NO_WEBHOOK
            - COLLECTION_PAUSED
            - MONITOR_LIMIT_EXCEEDED
            - SEARCH_UNAVAILABLE
            - BATCH_LIMIT_EXCEEDED
            - BATCH_NOT_CANCELLABLE
            - BATCH_NOT_COMPLETED
            - IDEMPOTENCY_KEY_CONFLICT
            - DELIVERY_IN_PROGRESS
            - DELIVERY_ALREADY_DELIVERED
            - DELIVERY_EXPIRED
            - DELIVERY_CANCELLED
          description: Error code indicating the type of error
        required_permission:
          type: string
          enum:
            - logs:read
            - data:execute
            - monitors:read
            - monitors:write
            - batches:read
            - batches:write
            - webdbs:read
            - webdbs:write
          description: >-
            Permission required for this request when error_code is
            INSUFFICIENT_PERMISSIONS. Manage (write) also grants read access to
            the same resource group.
        key_metadata:
          $ref: '#/components/schemas/KeyMetadata'
        request_id:
          $ref: '#/components/schemas/RequestId'
      required:
        - request_id
    PartialTimeout:
      type: object
      properties:
        milliseconds:
          type: integer
          minimum: 1000
          maximum: 300000
          description: 'Request deadline in milliseconds. Maximum: 300000 (5 minutes).'
        behavior:
          type: string
          enum:
            - fail
            - return-partial
          default: fail
          description: >-
            What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT
            without charging credits. "return-partial" returns usable results
            collected so far; if none are available, the request still fails
            without charging credits. Partial results are not cached as complete
            results.
      required:
        - milliseconds
      additionalProperties: false
      description: >-
        Optional request deadline and behavior on timeout. For GET requests, use
        timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a
        JSON-encoded timeoutOpts object.
    RequestTags:
      type: array
      items:
        type: string
        minLength: 1
        maxLength: 50
      maxItems: 20
      description: >-
        Optional tags for tracking usage. Up to 20 tags, each 1 to 50
        characters.
      example:
        - production
        - team-alpha
    RequestId:
      type: string
      format: uuid
      description: >-
        Unique id of this API call, also sent in the X-Request-Id response
        header. Quote it when contacting support about a failed request.
      example: 3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91
  headers:
    RequestId:
      description: >-
        Unique id of this API call, sent on every response and mirrored as
        request_id in JSON bodies. Quote it when contacting support.
      schema:
        type: string
        format: uuid
    RateLimitLimit:
      description: Maximum requests per minute.
      schema:
        type: integer
        minimum: 1
    RateLimitRemaining:
      description: Requests remaining in the current minute.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: Unix timestamp in seconds when the rate limit resets.
      schema:
        type: integer
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Unauthorized:
      description: Unauthorized
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <API_KEY>`. Keys have
        full access by default.

````