PHP SDK: HTTP: Requests to a Website
Get the client with $ctx->http(). Take URLs from settings or verified links from the source. In these examples, catalog_url and api_url are run parameters. The platform controls networking, caching, requests per second, and cancellation.
Methods
withHeaders
withHeaders(array $headers): self
Return a copy of the client with additional HTTP headers. The original client is unchanged.
$http = $ctx->http()->withHeaders(['Accept' => 'application/json']);
$response = $http->get($ctx->param('api_url'));
Result and notes. Returns an HttpClient. Save the result or continue the chain; calling it without assigning the result does not change the original client.
withoutCache
withoutCache(): self
Return a client copy that fetches fresh responses without reading the cache.
$response = $ctx->http()->withoutCache()->get($ctx->param('catalog_url'));
Result and notes. Returns an HttpClient. Rate, permission, and network restrictions still apply.
get
get(string $url, bool $autoCaptcha = true): Response
Load a page or JSON from a URL with GET.
$response = $ctx->http()->get($ctx->param('catalog_url'));
if (!$response->ok()) { $ctx->abort('HTTP ' . $response->status); }
Result and notes. Returns a Response. HTTP 200 does not guarantee that the catalog exists; inspect the expected elements or fields.
post
post(string $url, array|string|null $body = null, bool $autoCaptcha = true): Response
Send a POST request with a body. To send exact JSON, serialize it explicitly and set Content-Type.
$body = json_encode(['page' => 1]);
$response = $ctx->http()->withHeaders(['Content-Type' => 'application/json'])->post($ctx->param('api_url'), $body);
Result and notes. Returns a Response. The body may be a string, array, or null; array encoding depends on the transport, so use a string for JSON.
request
request(string $method, string $url, array|string|null $body = null, bool $autoCaptcha = true): Response
Send a request with an explicit HTTP method. get or post is usually enough.
$response = $ctx->http()->request('GET', $ctx->param('catalog_url'));
Result and notes. Returns a Response. The method, URL, and optional body are passed to the transport. This method does not bypass site restrictions.
pool
pool(array $urls, bool $autoCaptcha = true): array
Load a small batch of independent URLs in parallel.
$responses = $ctx->http()->pool($ctx->param('product_urls', []));
foreach ($responses as $response) {
$ctx->log('HTTP response', ['status' => $response->status]);
}
Concurrency and response size. The regular profile accepts 1 to 8 URLs and runs at most two requests at a time. A self-hosted agent with the High throughput profile accepts up to 6000 URLs. Actual concurrency is bounded by the site's concurrency setting and the network service's shared capacity. The rps rate, burst, robots.txt and other site policies still apply.
Responses preserve input order. The total SDK response, including metadata, is limited to 8,000,000 bytes. Use smaller batches for large HTML pages and process batches in sequence. A network exception or an exceeded size limit fails the pool; bodies are never silently truncated. An HTTP status such as 404 or 500 is not a network exception by itself: inspect status and $response->ok() on each response. 6000 HTTP requests do not mean 6000 browsers or scripts. See High HTTP throughput on your agent.
pages
pages(string $template, int $from, int $to, bool $autoCaptcha = true): iterable
Visit a known range of pages in order. Use {page} in the template for the page number.
foreach ($ctx->http()->pages('https://shop.example.invalid/catalog?page={page}', 1, 3) as $number => $response) {
$ctx->log('Page received', ['page' => $number]);
}
Result and notes. Returns an iterable of page number → Response. Determine the last page from the source, or you may miss products. Both from and to are included.
tryJson
tryJson(array $urls, bool $autoCaptcha = true): ?array
Try several JSON addresses in order and use the first suitable response.
$data = $ctx->http()->tryJson($ctx->param('api_candidates', []));
if ($data === null) { $ctx->abort('JSON source not found'); }
Result and notes. Returns an array or null. Unsuccessful HTTP responses and invalid JSON are skipped; network exceptions are not automatically suppressed. Check the returned array's structure.
Automatic CAPTCHA handling
autoCaptcha is optional and defaults to true. Pass false to disable automatic solving. With automatic mode disabled, the request does not start paid CAPTCHA tasks. Platform and site settings, supported challenge types and quotas still apply. This argument is also available in get, post, request, pool, pages and tryJson.
$response = $ctx->http()->get($url, autoCaptcha: false);
CAPTCHA on a self-hosted agent
Automatic mode and opt-out also work on your agent. A browser, connectivity to Akmelo and an eligible plan are required. No additional CAPTCHA keys need to be configured. Checks and costs belong to the agent's workspace; local execution does not make CAPTCHA handling free.
CAPTCHA usage reference
Complete CAPTCHA SDK and REST reference covers all hint fields, automatic defaults, explicit calls, session opt-out, result verification, agents, limits and failures. User guide and current prices explain setup and billing.
Object selection uses kind: "yandex_image"; automatic detection normally needs no hints. image_selector identifies only the task image, instructions_selector the selection order, and success_selector a result that appears after success. No target-domain list is needed. Unsupported variants fail instead of returning fabricated data. Do not repeatedly retry the same rejected task.