Apify Custom Proxy URLs: Actor Setup Guide

import { Actor } from 'apify';

// Use inside your Actor's initialized runtime.
// PROXY_URL is a complete, encoded HTTP proxy URL.
const proxyConfiguration = await Actor.createProxyConfiguration({
  proxyUrls: [process.env.PROXY_URL],
});
// Pass proxyConfiguration to your crawler's constructor options.
// Standalone fetch() calls are not configured by this assignment.
// Do not print proxy URLs or proxyInfo objects with credentials.

Apify supports external proxy URLs, but the place you enter them depends on the Actor you run. Some Actors expose a proxy configuration section in their input form. When building your own Actor, you can configure a proxy through the SDK. Check that path before purchasing traffic for an existing Actor.

Start with the Actor's input

Apify's own-proxy guide explains the Console route: open the Actor's Input tab and look for its proxy configuration section. That section is available when the Actor's input schema defines it. An Actor without that field may require a code change or a different documented input; do not assume every Store Actor accepts the same JSON.

Read the Actor's own input documentation and identify which requests use the supplied proxy. Save a copy of the configuration with credentials removed, together with the Actor version used for the test. This makes a later comparison more useful than a screenshot that shows only a green completion indicator.

For your own Actor, use the SDK configuration

The JavaScript SDK guide distinguishes custom URLs supplied through proxyUrls or newUrlFunction from settings for Apify's own proxy service. The configuration object can then be passed to a crawler. Keep the provider choice explicit instead of carrying unrelated Apify Proxy options into a custom-provider configuration.

A session identifier used by a crawler and a routing identifier understood by your external provider are different inputs. Check how both behave before promising address persistence across a login or multi-page task. Repeatedly returning the same gateway URL alone does not establish that the gateway will select the same exit.

Run one Actor before scaling it

1. Select an Actor whose input or source documents external proxies.
2. Obtain an active proxy route. The Proxies.sx gateway guide covers connection details.
3. Set a small request limit and use a page you control or have permission to access.
4. Verify the network route from the Actor, then inspect its saved output for the fields the task actually needs.
5. Repeat with the same Actor version. Record request failures, missing fields, elapsed time and transferred bytes before increasing concurrency.

Keep test costs separate. Actor execution and any Actor-specific fees belong to one part of the budget; the external proxy's traffic belongs to another. Compare cost per usable output record, including retries. Include the time spent repairing missing records when comparing two runs.

What to publish with an integration example

A useful example identifies the Actor input, supported proxy protocol, where secrets are stored and how to reproduce a small test. Include a sanitized result and the date of the run. Leave private addresses, account identifiers and passwords out of screenshots and example datasets.

Can I paste proxy URLs into every Actor?

Only use a field or code path documented by that Actor. Apify's Console guidance makes the input-schema requirement explicit.

Are external proxy costs included in an Actor run?

Check the Actor's pricing and your external provider's bill separately. This page does not quote a combined price.

For a broader product comparison, read our ScraperAPI, Apify and Proxies.sx comparison. Use the proxy test plan for the practical evaluation.