ScraperFlyAI-ready Web Data API

proxies

Web Scraping API with sticky sessions

ScraperFly helps teams preserve request continuity for public scraping workflows that depend on cookies, state, pagination, filters, region, or related requests, without making every one-off fetch stateful by default.

Session continuity

Keep request state stable when public pages depend on continuity

Some public scraping workflows are not truly one-request jobs. A target may set cookies, remember consent state, keep filters active, preserve pagination context, or expect several related requests to use the same delivery path. If that state disappears between requests, the next response can look incomplete, redirected, inconsistent, or simply different from the page your workflow expected.

ScraperFly sessions give teams a controlled way to preserve useful request context without making every scrape stateful by default. Start with a simple request, compare the response, then add session continuity only where repeated samples prove that cookies, route state, headers, rendering, or routing context actually changes the result.

sticky sessionscookie contextstateful workflows
Data engineer reviewing sticky session continuity across related web scraping API requests

What are sticky sessions in web scraping?

Sticky sessions keep request context stable across related public page requests. In practice, that can mean preserving cookies, state, or routing continuity so a sequence of requests behaves like one connected workflow instead of several unrelated fetches. The value is not the word session itself. The value is receiving a consistent public response when the target depends on continuity.

A stateless request is still the best default for many pages. If the target returns useful HTML, text, Markdown, metadata, screenshot, or PDF output without state, adding a session only makes the request profile harder to reason about. Use sessions when the response proves that continuity matters.

Practical takeaway: sessions are for related requests that need continuity, not for every public page capture.

When should a scraping workflow use sessions?

Use sessions when the target response changes after the first request or when later requests depend on state established earlier. Common examples include consent flows, public filters, pagination, search refinements, region selection, language preferences, route state, and multi-step public interactions where the next page expects the previous context to remain present.

Sessions are also useful when debugging response differences. If one request returns the expected public view and the next request loses it, the issue may be state continuity rather than proxy routing, JavaScript rendering, or parser logic. A session lets the team test that hypothesis cleanly.

Workflow signal What it suggests Best next action
First page sets cookies or consent stateLater requests may depend on stored contextTest a session across the related request sequence.
Pagination loses filtersState is not being preserved between pagesKeep the workflow in a stable session.
Content changes after region or language selectionThe public response depends on contextPair sessions with headers or country targeting when needed.
Rendered page works once but not laterBrowser state, cookies, or timing may affect the responseCompare rendering with and without session continuity.
One-off URL returns useful contentState is not requiredKeep the request stateless and lighter.

Are sessions the same as cookies?

No. Cookies are one part of request context. A session is the broader continuity model that keeps related requests connected. A session may preserve cookies, but the business reason for using it is usually larger: stable pagination, repeated public requests, consistent routing, selected preferences, or a workflow that needs the same context across steps.

This distinction keeps implementation cleaner. If a single header solves the response, use a header. If rendering solves the response, use rendering. If country targeting solves a regional difference, use country targeting. If related requests need shared state, use a session. Each control should have a reason.

Control What it preserves or changes Use it when
CookiesStored target stateThe public response depends on consent, preferences, or target-set values.
SessionContinuity across related requestsA sequence needs stable context from one request to the next.
HeadersLegitimate request contextThe target varies by language, user agent, referer, or accepted content type.
Country targetingRegional delivery contextThe public page changes by location, currency, availability, or redirect rules.
Premium routingStronger delivery pathThe simple path repeatedly fails after the request is valid.
RenderingBrowser-executed page stateJavaScript creates the useful content after the first HTML response.

How do sessions work with proxy routing and rendering?

Sessions, routing, and rendering can work together, but they solve different problems. A session keeps continuity. Routing changes the delivery path. Rendering executes JavaScript. Headers carry request context. Country targeting requests a regional view. Premium routing is an escalation for harder public targets. Combining all of them by default makes the request heavier and harder to debug.

The better pattern is to test one reason at a time. If source HTML is thin, test rendering. If the page changes by region, test country targeting. If repeated requests lose state, test sessions. If the simple route repeatedly returns block behavior after the request is valid, test stronger routing. A session should be part of a proven request profile, not a guess.

For adjacent controls, compare rotating proxy scraping, custom headers, and the JavaScript rendering API.

What should teams inspect before scaling session scraping?

Before a stateful workflow becomes a batch job, inspect the actual response evidence. Check status code, final URL, content type, response size, cookies, redirects, rendered output, screenshot output, and whether later pages keep the expected state. If the page returns the same useful result without a session, do not carry session complexity into production.

For workflows that do need state, make the session behavior visible in logs and request profiles. When a scrape fails later, the team should know whether the request used a session, which output format was requested, whether rendering ran, whether routing changed, and whether the response was actually different.

How can session scraping stay affordable?

Sessions add value when continuity improves the result, but they should not become the default for unrelated one-off pages. The cost-aware workflow is simple: keep stateless captures stateless, use sessions for route classes that need continuity, and add rendering, premium routing, country targeting, screenshots, or PDFs only where the target proves those controls improve the response.

ScraperFly's pricing model supports this gradual path. Teams can start free, test real public targets, use pay-as-you-go credits for uneven projects, and move recurring stateful workflows to monthly credits only after the request profile is understood.

Review pricing after testing representative session routes, then use the API Builder to copy a request profile your production code can repeat.

Where should a team start?

Start with one public URL and a normal stateless request. If the response is useful, keep the workflow light. If later requests lose cookies, filters, consent, pagination, or regional state, test a session with the smallest related sequence that proves the difference. Then choose the output format your product can use: HTML for parsers, text or Markdown for readable content, JSON metadata for diagnostics, and screenshots or PDFs for visual proof.

That approach keeps the session decision practical. The team gets the continuity it needs without turning every scrape into a heavier stateful job, and failures become easier to explain from evidence rather than assumptions.

Session scraping

Keep continuity across requests when the target depends on state

Some public workflows behave differently after the first request: cookies, region selection, consent state, pagination, filters, or navigation can affect later responses. ScraperFly sessions help teams preserve useful continuity while keeping the request profile visible and testable.

Raw HTML response mapped to visible page data
01

Raw HTML availability

Check whether the fields you need are already present in the first HTML response.

Best first test for simple pages, articles, docs, listings, and product details.

Before and after JavaScript rendering comparison
02

JavaScript dependency

Compare raw HTML with the rendered DOM or screenshot before turning on browser rendering.

Use rendering when raw HTML is only a shell and scripts create the useful content.

Cookies, consent, session and access context for scraping
03

State & access context

Identify whether cookies, consent, login boundaries, pagination, or the same visitor state affect the response.

Use sessions and headers when continuity changes the data you receive.

Regional content variations across countries and routes
04

Geo/content variation

Test whether country, language, currency, inventory, SERP, ads, or route reputation changes the result.

Use geo or premium routing only when the target proves the response varies by route.

Checks before using scraping sessions

Where is the target field?

Find whether the field exists in raw HTML, rendered DOM, an API call, structured data, a file, or a later interaction state.

What changes the response?

Sample a few URLs and compare status, final URL, content length, redirects, empty states, and visible result differences.

What context is required?

Mark any dependency on consent, locale, cookies, headers, authentication boundary, pagination, filters, or previous requests.

What does failure look like?

Define the signals for blocked, partial, stale, redirected, empty, timed-out, or region-mismatched responses before scaling.

How session behavior changes scraping setup

Fetch mode

Raw HTML availability decides whether the first request can stay simple or needs rendering, waits, screenshots, or extraction.

Request context

State requirements decide whether to add headers, cookies, sessions, consent handling, or a stable visitor profile.

Routing choice

Geo and reputation findings decide whether standard routing is enough or a country/premium route is justified.

Validation rules

Known failure states become checks for retries, escalation, QA review, and deciding when a lighter profile is still complete.

Session request builder

Build stateful scraping requests without making every target heavier

Start with a simple request, then add session continuity when repeated samples prove the target depends on stored state. Pair sessions with rendering, headers, country routing, or premium delivery only when the response evidence calls for it.

S1
Continuity

Preserve request state across related pages

Sessions help when cookies, consent, pagination, filters, or route state affect what the target returns.

sessioncookies
CTRL
Controls

Combine sessions with only the controls that matter

Rendering, headers, country targeting, premium routing, and waits can stay modular instead of becoming automatic defaults.

renderheaderscountry
QA
Evidence

Compare responses before scaling stateful jobs

Status, final URL, response size, content type, and output shape reveal whether session continuity improves the scrape.

statussampleslogs

Controls that shape session scraping

url

The public page being fetched as part of a stateful workflow.

session

Continuity for related requests that depend on stored state.

headers

Optional request context when the target varies by client signal.

render

Browser execution when JavaScript also affects the stateful response.

cURL example

Generate Markdown with the same request shape you can move into production

curl "https://scraperfly.com/api/v1?url=https%3A%2F%2Fexample.com&format=markdown" \
  -H "apikey: YOUR_API_KEY"

Error handling

Turn scraping failures into fixes

Every web data workflow eventually meets a bad response: a missing URL, an invalid key, an empty HTML shell, a target 403, a rate limit, a render timeout, a broken PDF capture, or a JSON payload that does not contain the fields your product expected. ScraperFly is built to make those moments diagnosable. You inspect the HTTP status, the stable error code, the request profile, and the returned artifact, then choose the cheapest useful next move: fix the request, add credits, slow down, retry with backoff, enable rendering, change country, use premium routing, preserve headers, or validate the output before scaling.

Stable error shapeRetry decisionsCost-aware escalationOutput validation
Developer reviewing code and API request parameters on a laptop

01 / Request setup and access

Fix request mistakes first

Some failures are not target problems at all. They happen before ScraperFly can make a meaningful delivery attempt: a missing or malformed URL, an unsupported output format, an incompatible visual file type, a missing API key, an invalid key, or a key that has been paused or disabled. These errors are configuration signals, not retry signals: stop the workflow, point the developer to the exact field that needs correction, and keep credits focused on real target tests instead of repeated bad inputs.

missing_urlinvalid_urlunsupported_formatinvalid_api_key
  • Validate the URL and encoding before sending a batch.
  • Use supported outputs: HTML, text, Markdown, JSON, screenshot, or PDF.
  • Match screenshot file types to image output and PDF file type to PDF output.
  • Treat missing or invalid API keys as configuration work, not retry work.
Business dashboard with charts, documents and usage planning on a desk

02 / Credits, limits and concurrency

Separate limits from failures

A workload can fail because the account has no usable credits, the monthly plan limit has been reached, or concurrency is too aggressive for the current plan and target mix. ScraperFly makes those limits visible as operating signals, not mysterious scrape failures. That keeps the buying decision practical: start free, test the target, buy pay-as-you-go credits for uneven jobs, move to monthly credits when volume becomes predictable, and use backoff when request pressure is the real issue.

usage_limit_reachedrate_limitedcreditsbackoff
  • Use account status to check remaining credits before large runs.
  • Retry rate limits with backoff instead of immediately increasing pressure.
  • Keep one-off projects on pay-as-you-go when volume is uneven.
  • Move predictable recurring work to monthly credits when the pattern is proven.
Server room representing delivery paths, routing and network infrastructure

03 / Target delivery and network

Find delivery failures first

Many scraping platforms collapse delivery issues into a vague request failure. In production, that is not enough. The team needs to know whether the request timed out, the upstream target returned a temporary server error, the connection failed, the response was too large, redirects went somewhere unexpected, or the page came back as tiny HTML with no useful content. ScraperFly turns those failures into delivery evidence: try the light profile first, compare status and response size, then decide whether the next request needs backoff, another route, premium proxy, country targeting, or a narrower capture.

timeout5xxredirectsresponse_too_large
  • Retry temporary network and upstream failures with a controlled backoff policy.
  • Compare final URL, status, content type and response size across samples.
  • Escalate routing only when the response proves the simple path is unstable.
  • Treat oversized responses as a scope problem before scaling the same profile.
Digital security screen representing anti-bot and protected access signals

04 / Anti-bot, geo and access blocks

Read blocks before escalation

A target 403, 401, 429, CAPTCHA screen, WAF challenge, login wall, consent loop, or region-specific mismatch is not just an error; it is a clue about what the site expects from the visitor. Competitors often push teams toward a heavier default profile, but that can burn budget without proving the fix. ScraperFly's better path is evidence-based escalation: preserve realistic headers when context matters, use sessions when continuity changes the response, enable rendering when the useful content is browser-built, and choose premium or country routing when reputation or geography changes the result.

403429CAPTCHAcountry mismatch
  • Use premium routing when IP reputation is the proven bottleneck.
  • Use country targeting when language, currency, inventory or search results change by market.
  • Use headers, cookies and sessions when visitor state changes the response.
  • Reduce concurrency and add backoff when repeated requests trigger target throttling.
Developer preparing code and output artifacts on a laptop

05 / Rendering and output quality

Ship usable artifacts

A 200 status is not the same thing as a usable scrape. The raw HTML can be an empty app shell, Markdown can miss the main article, JSON can lack expected metadata, text can include noise, screenshots can be blank, and PDF or image output can fail if the browser step times out. ScraperFly is valuable because the same API request can move from raw HTML to rendered DOM, clean text, Markdown, JSON, screenshot or PDF, then be checked against the artifact your product actually needs. That reduces glue code, failed imports, and expensive batch runs that only discover bad output after the fact.

render_timeoutbrowser_render_failedJSON fieldsPDF/image output
  • Enable rendering when raw HTML is only a shell and the useful content appears after JavaScript.
  • Validate text, Markdown and JSON against expected fields before batching.
  • Use screenshot or PDF output when visual proof or audit evidence matters.
  • Treat blank or partial artifacts as quality failures even when HTTP status is successful.
ScraperFly fit

Cleaner error recovery

ScraperFly helps teams decide what to fix, what to retry, and what to escalate without turning every scrape into the most expensive request profile.

Stable error shape

Use HTTP status and error code together so application logic can choose between fixing input, refreshing credentials, slowing down, retrying, or escalating delivery.

Retry only when it helps

Network failures, rate limits, and temporary server errors can use backoff. Invalid URLs, unsupported formats, and bad keys should be corrected once.

Cost-aware escalation

Start with the light request profile, then add rendering, premium routing, country, sessions, headers, waits, or visual capture only when the failure proves it.

Validate output before scale

Confirm the real artifact your product needs: HTML, text, Markdown, JSON, screenshot, or PDF, before copying the same profile across a large URL set.

Session cost

Use sessions where continuity improves the result

Sessions add value when state changes the response. For one-off pages that return stable content, lighter stateless requests keep scraping cheaper and easier to reason about.

A lightweight HTML request returning a simple response
01

Basic fetch

Use a basic fetch when public HTML already contains the fields you need.

Lightest request profile; keep it when the response is complete.

JavaScript rendering producing a complete DOM
02

Rendering

Use rendering when raw HTML is a shell and JavaScript completes the page.

Heavier profile; use it only when browser output changes the result.

Several requests preserving cookies and visitor state
03

Stateful session

Use sessions when cookies, consent, locale, or pagination change the response.

Heavier state profile; preserve it only when continuity matters.

Request routing through geo and higher quality routes
04

Premium routing & geo

Use premium routing or geo only when origin, country, reputation, or regional content changes the result.

Heaviest routing profile; apply it only to targets that prove they need it.

What makes session scraping heavier

More infrastructure work

Browser rendering, routing choices, and longer waits mean the platform has to do more than return a simple response.

More target uncertainty

Redirects, empty states, rate limits, and challenge pages often require stronger delivery options or retries.

More state to preserve

Cookies, sessions, consent, and multi-page flows add moving parts that a plain stateless fetch does not have.

More evidence to return

Screenshots, PDFs, rendered output, and richer response artifacts are useful, but they are heavier than plain HTML.

How to keep stateful scraping predictable

Sample before scale

Test a small URL set first and group targets by the lightest profile that returns complete data.

Do not render by default

Inspect raw HTML before turning on rendering. Many public pages already contain the data you need.

Escalate by evidence

Move up only when the response shows missing content, state dependency, geo variance, or routing problems.

Measure useful results

Optimize around valid records delivered, not raw request volume. A lighter profile is best only when it stays complete.

Session questions

Common questions about web scraping sessions

Practical answers for teams deciding when cookies, session continuity, routing, headers, and rendering should be part of a public page capture workflow.

Session FAQ
Continuity

When sessions help

Use sessions when related requests depend on shared public state.

What are sticky sessions?

Sticky sessions keep related requests connected so cookies, preferences, or route state can remain stable across a workflow.

When are sessions unnecessary?

If a one-off public URL returns useful content without state, keep the request stateless and easier to debug.

Cookies

Cookies and state

Cookies are only one part of session behavior.

Are sessions just cookies?

No. Cookies may be preserved inside a session, but the session is the larger continuity boundary across related requests.

What state can matter?

Consent, filters, pagination, route choices, preferences, language, region, and target-set values can all affect later responses.

Controls

Routing and rendering

Sessions can combine with other controls when evidence supports it.

Can sessions use proxy routing?

Yes. Use routing with sessions when continuity and delivery path both affect the public response.

Can sessions use rendering?

Yes. Rendering handles JavaScript-built content, while sessions preserve state across related rendered requests.

Cost

Predictable stateful jobs

Keep stateful scraping tied to route classes that prove they need it.

How do sessions affect cost?

Sessions can make workflows heavier when paired with rendering, routing, visual outputs, or retries, so use them where continuity improves the result.

Where should I test sessions?

Use the API Builder with a small related request sequence before moving a stateful profile into production.