API

Standby mode

Serve HTTP from a warm Actor container, with autoscaling, billing, and errors.

Standby mode lets an Actor run as an always-on HTTP service. Instead of starting a fresh run for every request, the platform keeps a warm container alive and forwards your HTTP requests to it. It suits real-time APIs, on-demand scraping endpoints, and webhook receivers.

How it works

When you send an HTTP request to a standby-enabled Actor URL, Scrape.ly:

Finds the Actor by username/actorName (the username is case-insensitive).
Checks access: the Actor must be public, or yours.
Checks that standby mode is enabled.
Picks one of your standby runs of that Actor, or starts a new one. If the run is still starting (for example, another request just started it), Scrape.ly waits up to 5 minutes for it to become ready.
Checks your effective balance (balance minus credits reserved by other running jobs).
Forwards the request (method, path, query, headers, and body) to the container's web server.

Standby runs belong to the caller. Each user who calls a standby Actor gets their own runs, billed to their own account; your requests never go to another user's container.

A standby run stays alive while requests keep arriving, and stops after it has been idle for the Actor's idle timeout (5 minutes by default). Each request resets the idle timer.

The platform does not start an HTTP server for you. Your Actor process must listen on the web-server port (ACTOR_WEB_SERVER_PORT, 4321). If nothing is listening, requests fail because the container is not ready.

Endpoints

Authentication is always required, sent in the Authorization: Bearer header. All HTTP methods are accepted (GET, POST, PUT, PATCH, DELETE, HEAD, and others).

GET/v2/{username}/{actorName}

POST/v2/{username}/{actorName}

GET/v2/{username}/{actorName}/{path}

POST/v2/{username}/{actorName}/{path}

Both the Actor root and any subpath are forwarded. The subpath and query string are passed to the Actor's web server as they are.

.bash

curl "https://api.scrape.ly/v2/jane/my-api" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN"

curl -X POST "https://api.scrape.ly/v2/jane/my-api/scrape?url=https://example.com" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "depth": 1 }'

Path param	Type	Description
`username`	string	The Actor owner's username (case-insensitive).
`actorName`	string	Actor name.
`path`	string	Optional. Forwarded to the Actor's HTTP server.

The response is whatever the Actor returns: status code, headers, and body are passed through.

Before forwarding, the platform removes your credentials: Authorization, Proxy-Authorization, Cookie, and every X-Scrapely-* header are stripped, so the Actor never sees your API token. If your Actor needs its own authentication, use a different header or a query parameter.

These URLs share the /v2 namespace with the rest of the API, and the standby route is matched last. A username or Actor name that collides with an API path (for example /v2/actors/...) is handled by that API route instead.

Enabling standby mode

Enable standby in the Actor's settings in the dashboard, or set actorStandby with the Update Actor endpoint. Requests to an Actor that exists but doesn't have standby enabled return 400 standby-not-enabled.

`actorStandby` field	Default	Description
`isEnabled`	`false`	Turns standby mode on.
`build`	`latest`	Build tag or number that standby runs use. It must be a successful build. Other users' standby runs use the User Build when it's set.
`memoryMbytes`	`2048`	Memory for each standby run.
`idleTimeoutSecs`	`300`	Seconds without requests before a standby run stops.
`desiredRequestsPerActorRun`	`100`	Load target per run. When your runs average more than 80% of this, the next request starts another run.
`maxRequestsPerActorRun`	none	Hard cap. A run that has served this many requests is stopped and replaced.

Standby runs have a 24-hour run timeout; the idle timeout normally ends them first.

Full-permission Actors need approval before your first standby request starts a run. Otherwise the request returns 403 full-permission-actor-not-approved.

Readiness

A GET or HEAD request to the Actor root that carries an x-scrapely-standby-readiness-probe (or x-apify-container-server-readiness-probe) header is answered by the platform itself with 200 and { "status": "ready", "timestamp": "..." }. It is not forwarded and doesn't start a run.

For real traffic, your Actor still has to bind the web-server port. See Standby mode in the JavaScript SDK for how to read the port and start a server.

Billing

Standby runs are billed to the caller like normal runs: compute time while the container is alive, plus platform usage. Requests are rejected with 402 insufficient-funds if your effective balance is zero or negative.

Errors

Status	Type	Meaning
400	`standby-not-enabled`	The Actor exists but standby mode is off.
400	`actor-not-available`	Someone else's Actor has no build you can run right now.
401	`token-not-provided` / `token-not-valid`	Missing or invalid `Authorization` header.
402	`insufficient-funds`	Effective balance is zero or negative.
403	`forbidden`	Private Actor you don't own.
403	`full-permission-actor-not-approved`	The Actor needs full permissions and you haven't approved it.
404	`actor-not-found`	Unknown `username/actorName`.
500	`standby-error`	A standby run could not be started, for example because your own Actor has no successful build or there's not enough credit. The message says why.
502	`proxy-error`	The request could not be forwarded to the container.
503	`standby-timeout`	A new standby run did not become ready within 5 minutes.
503	`standby-not-ready`	An existing standby run that was still starting did not become ready within 5 minutes.
503	`container-unavailable`	The standby run's web server refused the connection, for example because it stopped. Retry.
503	`container-owner-unavailable`	The server hosting the container cannot be reached. Retry.
504	`container-timeout`	The Actor did not respond within 5 minutes.

Standby mode in the JavaScript SDK: writing an Actor that serves HTTP
Actors API: Actor settings, builds, and permission approvals