> ## 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.
# Scrape Bytes
> Download images, PDFs, HTML, and other resources as base64-encoded bytes with their content type and download metadata.
1 Credit
Decode the `bytes` field from base64 to recover the downloaded file. HTTP compression is decoded before base64 encoding. Downloads support up to 20 MiB (20,971,520 bytes) before base64 encoding and are not cached.
HTML is returned as the original HTTP response without rendering JavaScript. For rendered page content, use [Scrape HTML](/api-reference/web-scraping/html) or [Scrape Markdown](/api-reference/web-scraping/markdown).
Follow [Download resource bytes](/guides/download-resource-bytes) for cURL and SDK examples that decode and save the file. Bytes supports only `timeoutOpts.behavior: "fail"`; the complete download must fit within the deadline.
## OpenAPI
````yaml GET /web/scrape/bytes
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/scrape/bytes:
get:
tags:
- Web Scraping
summary: Scrape raw bytes
description: >-
Downloads a resource and returns its bytes as base64. Supports images,
PDFs, HTML pages, and any other content type without image conversion,
text extraction, or character-encoding changes. HTTP compression is
decoded before base64 encoding. HTML is the original HTTP response;
JavaScript is not rendered. Follows public redirects and retries failed
downloads through ISP and residential proxies, with a direct fallback.
When country is specified, only a residential proxy in that country is
used. Supply headers such as Referer for images that require a referring
page. Downloads are not cached. Maximum decoded resource size: 20 MiB
(20971520 bytes), before base64 encoding. Successful requests cost 1
credit; errors are not billed.
parameters:
- schema:
type: string
minLength: 1
format: uri
description: >-
Full HTTP(S) URL of the resource to download, such as an image,
PDF, or page.
required: true
description: >-
Full HTTP(S) URL of the resource to download, such as an image, PDF,
or page.
name: url
in: query
- schema:
type: object
additionalProperties:
type: string
maxLength: 8192
pattern: ^[^\r\n]*$
description: >-
Optional outbound HTTP headers, such as Referer, Cookie, or
Authorization. Send as a JSON object or deep-object query params
such as headers[Referer]=https://example.com/. Host,
Content-Length, and hop-by-hop transport headers are rejected.
Authorization and cookies are removed when a redirect changes
origin.
required: false
description: >-
Optional outbound HTTP headers, such as Referer, Cookie, or
Authorization. Send as a JSON object or deep-object query params
such as headers[Referer]=https://example.com/. Host, Content-Length,
and hop-by-hop transport headers are rejected. Authorization and
cookies are removed when a redirect changes origin.
name: headers
in: query
- schema:
$ref: '#/components/schemas/BrowserCountryCode'
required: false
description: >-
Fetch the target page through a residential proxy in this country
(ISO 3166-1 alpha-2).
name: country
in: query
- schema:
$ref: '#/components/schemas/LenientTimeout'
required: 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.
style: deepObject
explode: true
name: timeoutOpts
in: query
- schema:
type: string
enum:
- enabled
- disabled
default: disabled
description: >-
Set to enabled to bypass shared caches and omit request and
response content from retained usage logs. Requires zero data
retention to be enabled for your organization (contact
support@context.dev), otherwise the request fails with
ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR:
true.
required: false
description: >-
Set to enabled to bypass shared caches and omit request and response
content from retained usage logs. Requires zero data retention to be
enabled for your organization (contact support@context.dev),
otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR
responses include X-Context-ZDR: true.
name: zdr
in: query
- $ref: '#/components/parameters/RequestTags'
responses:
'200':
description: Resource bytes and download metadata
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'
X-Context-ZDR:
description: >-
Present with the value true when zero data retention was
requested and honored.
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- true
url:
type: string
format: uri
description: The requested resource URL.
finalUrl:
type: string
format: uri
description: The resource URL after redirects.
bytes:
type: string
format: byte
description: >-
Base64-encoded resource bytes, without a data URI prefix.
Decode this field to recover the downloaded file.
encoding:
type: string
enum:
- base64
contentType:
type: string
description: >-
The Content-Type returned by the origin, including any
charset. Defaults to application/octet-stream when absent.
contentLength:
type: integer
minimum: 0
maximum: 20971520
description: Number of decoded resource bytes, before base64 encoding.
statusCode:
type: integer
minimum: 200
maximum: 299
description: HTTP status returned by the origin.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- success
- url
- finalUrl
- bytes
- encoding
- contentType
- contentLength
- statusCode
- request_id
'400':
description: Bad request - Invalid URL or failed to scrape
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:
message:
type: string
description: Error message describing the issue
error_code:
type: string
enum:
- INPUT_VALIDATION_ERROR
- TIMEOUT_TOO_SHORT_FOR_WAIT
- WEBSITE_ACCESS_ERROR
- WEBSITE_BLOCKED
description: >-
Error code indicating the type of error.
TIMEOUT_TOO_SHORT_FOR_WAIT means timeoutOpts.milliseconds
is shorter than waitForMs plus the page-load margin, so
the request could never complete; raise
timeoutOpts.milliseconds or lower waitForMs.
WEBSITE_BLOCKED means the site answered with an anti-bot
challenge, CAPTCHA wall, or login shell instead of the
page (often as an HTTP 200) — the request is not billed,
and retrying later or from another country sometimes
succeeds.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
- message
- error_code
'401':
description: Unauthorized - Invalid or missing API key
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:
message:
type: string
description: Error message
error_code:
type: string
enum:
- UNAUTHORIZED
description: Error code indicating unauthorized access
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
'403':
description: Forbidden - Insufficient permissions or usage limit exceeded
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:
message:
type: string
description: Error message
error_code:
type: string
enum:
- FORBIDDEN
- USAGE_EXCEEDED
- DISABLED
- INSUFFICIENT_PERMISSIONS
description: Error code indicating forbidden access
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
'404':
description: Target page returned a 404
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:
message:
type: string
description: Error message describing the issue
error_code:
type: string
enum:
- NOT_FOUND
description: Error code indicating the target page was not found
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
- message
- error_code
'408':
description: Request timeout
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:
message:
type: string
description: Timeout error message
error_code:
type: string
enum:
- REQUEST_TIMEOUT
description: Error code indicating request timeout
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
'413':
description: >-
Content too large - the target content exceeds the maximum supported
download size, so it cannot be scraped
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:
message:
type: string
description: >-
Error message naming the URL and the maximum supported
size
error_code:
type: string
enum:
- CONTENT_TOO_LARGE
description: >-
Error code indicating the target content exceeds the
maximum supported size
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
- message
- error_code
'429':
$ref: '#/components/responses/RateLimited'
'500':
description: Internal server error
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:
message:
type: string
description: Error message
error_code:
type: string
enum:
- INTERNAL_ERROR
description: Error code indicating internal server error
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
security:
- bearerAuth: []
components:
schemas:
BrowserCountryCode:
type: string
enum:
- ad
- ae
- af
- ag
- ai
- al
- am
- ao
- ar
- at
- au
- aw
- az
- ba
- bb
- bd
- be
- bf
- bg
- bh
- bi
- bj
- bm
- bn
- bo
- bq
- br
- bs
- bw
- by
- bz
- ca
- cd
- cf
- cg
- ch
- ci
- cl
- cm
- cn
- co
- cr
- cv
- cw
- cy
- cz
- de
- dj
- dk
- dm
- do
- dz
- ec
- ee
- eg
- es
- et
- fi
- fj
- fr
- ga
- gb
- gd
- ge
- gf
- gg
- gh
- gm
- gn
- gp
- gq
- gr
- gt
- gu
- gw
- gy
- hk
- hn
- hr
- ht
- hu
- id
- ie
- il
- im
- in
- iq
- ir
- is
- it
- je
- jm
- jo
- jp
- ke
- kg
- kh
- kn
- kr
- kw
- ky
- kz
- la
- lb
- lc
- lk
- lr
- ls
- lt
- lu
- lv
- ly
- ma
- mc
- md
- me
- mf
- mg
- mk
- ml
- mm
- mn
- mo
- mq
- mr
- mt
- mu
- mv
- mw
- mx
- my
- mz
- na
- nc
- ne
- ng
- ni
- nl
- 'no'
- np
- nz
- om
- pa
- pe
- pf
- pg
- ph
- pk
- pl
- pr
- ps
- pt
- py
- qa
- re
- ro
- rs
- ru
- rw
- sa
- sc
- sd
- se
- sg
- si
- sk
- sl
- sm
- sn
- so
- sr
- ss
- st
- sv
- sx
- sy
- sz
- tc
- td
- tg
- th
- tj
- tl
- tm
- tn
- tr
- tt
- tw
- tz
- ua
- ug
- us
- uy
- uz
- vc
- ve
- vg
- vi
- vn
- ye
- yt
- za
- zm
- zw
example: de
description: >-
Fetch the target page through a residential proxy in this country (ISO
3166-1 alpha-2).
LenientTimeout:
type: object
properties:
milliseconds:
type: integer
minimum: 1
maximum: 300000
description: 'Request deadline in milliseconds. Maximum: 300000 (5 minutes).'
behavior:
type: string
enum:
- fail
default: fail
description: >-
What to do at the deadline. This endpoint supports "fail": return
408 REQUEST_TIMEOUT without charging credits.
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.
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.
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
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
parameters:
RequestTags:
name: tags
in: query
required: false
style: form
explode: false
schema:
$ref: '#/components/schemas/RequestTags'
description: >-
Comma-separated tags for tracking request usage. Up to 20 tags, each
1-50 characters.
example: production,team-alpha
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:
RateLimited:
description: Rate limit exceeded
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'
Retry-After:
description: Seconds until the per-minute rate limit window resets
schema:
type: integer
minimum: 1
maximum: 60
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
error_code:
type: string
enum:
- RATE_LIMITED
description: Error code indicating the rate limit was exceeded
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
- message
- error_code
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form `Bearer `. Keys have
full access by default.
````