Skip to content
Pageteer
Docs menu

Getting started

Authentication & headers

Every request is authenticated with an API key from your dashboard, and every response reports its cost.

Bearer token

Send the key in the Authorization header on every request:

Header
Authorization: Bearer pk_live_…

On GET requests only (search, usage, job status and results) you can pass it as the api_key query parameter instead, which is handy for trying search in a browser or downloading batch results. It does not work on POST or DELETE. Prefer the header in code: query strings end up in logs and browser history.

GET with api_key
https://api.104-236-84-15.sslip.io/v1/search?q=example&api_key=pk_live_…

Managing keys

  • Create keys under API keys in the dashboard. A key is pk_live_ (or pk_test_, below) plus 40 letters and digits. The full key is shown exactly once; we store only a SHA-256 hash and a short prefix (like pk_live_AbCd) so you can tell keys apart.
  • Give each app or environment its own key, so you can revoke one without breaking the others.
  • Revoked keys return 401 invalid_api_key within a minute (key lookups are cached for up to 60 seconds).
  • Keep keys server-side. Never ship them in browser or mobile code; anyone with a key can spend your credits.
  • Keys belong to the team, not a person. All keys of a team share its credits, rate limit and concurrency.

Live and test keys

Every key has a mode, chosen when you create it and visible in its prefix:

  • pk_live_… keys fetch real sites, charge credits and count toward your spend limit.
  • pk_test_… keys are free. They never fetch real sites; they return deterministic fake responses marked with x-pageteer-test: 1 and "test": true. Validation, blocked targets and rate limits still apply, so a request that works with a test key works with a live one. See Test keys.

Both kinds authenticate the same way and share the team's rate limit and concurrency. A key's mode cannot be changed: create a new key instead.

Requests

  • Base URL: https://api.104-236-84-15.sslip.io/v1. Use HTTPS.
  • POST bodies are JSON with Content-Type: application/json, at most 64 KB (8 MB for POST /v1/batch).
  • The key is checked before the body is read, so a bad key is always a 401, whatever the body. A body that is not a JSON object is 415; a known path with the wrong method is 405 method_not_allowed with an Allow header.
  • Unknown fields are rejected with 400 invalid_request, so typos never fail silently. Fields such as js, script, actions, click, form, method or body get a specific message: the API does not run custom JavaScript, submit forms or send non-GET requests to sites.
  • Timeouts: set your HTTP client's timeout above the request's timeout_ms (default 30 s, max 120 s). 150 seconds is always enough.

Response headers

Response headers
HeaderSent onMeaning
x-request-idEvery responseA unique id (req_…) for the request. Log it and quote it when you contact support.
x-credits-usedEvery responseCredits this request cost. 0 for errors, cache hits, polling and usage.
x-credits-remainingEvery responseFree credits left this month after this request: max(0, granted − used). It stays at 0 once you are using billable credits; GET /v1/usage has the full picture. 0 on any response without a valid key.
x-ratelimit-limitAuthenticated requestsYour requests-per-minute limit.
x-ratelimit-remainingAuthenticated requestsRequests left in the current window.
retry-afterEvery 429Seconds to wait before retrying.
x-cacheSearch; target endpoints that sent max_ageHIT (served from cache, 0 credits), REVALIDATED (the site confirmed the cached copy) or MISS.
x-cache-ageWith x-cache HIT or REVALIDATEDSeconds since the cached copy was fetched or revalidated.
x-tier-usedScreenshot and PDFThe unblocking tier that produced the capture (the JSON responses carry tier_used instead).
x-proxy-sourceScreenshot and PDF, residential tier“customer” when your team’s own proxy produced the capture (the JSON responses carry proxy_source).
x-target-statusScreenshot and PDF as binaryThe target site’s HTTP status.
x-pageteer-testRequests with a test key1: the response is a free fake from a test key (JSON bodies also carry "test": true). Absent on live requests.
idempotent-replayedPOST /v1/batch and /v1/crawltrue when the response is a replay of an earlier submit with the same Idempotency-Key.
Headers of a real render
HTTP/1.1 200 OK
x-request-id: req_2d98773bc3c4412fb509b9964df57976
x-ratelimit-limit: 30
x-ratelimit-remaining: 28
content-type: application/json; charset=utf-8
x-credits-used: 1
x-credits-remaining: 999

A missing or bad key returns 401 with {"error":{"code":"invalid_api_key",…}}. See Errors.