# HTTP Request: Bulk API Calls, curl Import, JSON Fields (`joesimo/http-request`) Actor

Send GET, POST, PUT, PATCH or DELETE requests to any public API in bulk. Paste URLs or curl commands, or fill a URL template from rows. Get status, headers, JSON or text, extracted fields, array rows and pages. Failed calls are free.

- **URL**: https://apify.com/joesimo/http-request.md
- **Developed by:** [Joe Simo](https://apify.com/joesimo) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Features:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 requests

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## HTTP Request: Bulk API Calls, curl Import, JSON Fields

Send HTTP requests to any public API or web URL in bulk and get every response as a clean dataset row. Paste plain URLs, curl commands copied from API docs or your browser, or build one request per row from a URL template. Works with GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS.

Use it from Clay, n8n, Make, Zapier or the Apify API when your tool cannot call an API directly, or to run thousands of API calls in one run instead of one run per call.

### What you get for each request

- `status`, `ok`, `statusText`, `contentType`, `sizeBytes`, `durationMs`, `attempts`
- `json` (parsed), or `text`, or `base64` for binary bodies
- `fields`: values you pick from the JSON with simple paths like `data.items[0].name`
- `headers`: response headers (Set-Cookie is never saved)
- `redirects`: every hop with its status, and `finalUrl`
- `row`: your template row, echoed back so results join to your sheet or CRM
- `error` and `errorType` when something went wrong

A run summary (responses by status class, failures, retries, 429s, stop reason) is saved in the `OUTPUT` record.

### Features

- **curl import**: paste `curl -X POST 'https://api.example.com/v1/items' -H 'Content-Type: application/json' --data-raw '{"name":"test"}'`. Supports `-X`, `-H`, `-d`, `--data-raw`, `--data-urlencode`, `--json`, `-u`, `-G`, `-I`, `-A`, `-b`, `--url`.
- **Templates**: `https://api.example.com/users/{{id}}?country={{country}}` plus rows like `[{"id": 1, "country": "US"}]`. Placeholders work in URLs (URL encoded), headers, query parameters and bodies (JSON escaped).
- **Field extraction**: `{"title": "data.title", "firstTag": "data.tags[0]"}` puts just the values you need in a `fields` column.
- **Split arrays into rows**: set `splitArrayPath` to `data.items` and every element becomes its own row.
- **Pagination**: follow a next page URL or cursor from the JSON (`links.next`, `meta.next_cursor`) or the standard `Link: rel="next"` header, with a page limit per request.
- **Retries that are safe**: timeouts, network errors, 429 and 5xx are retried with backoff and `Retry-After`. POST and PATCH are only retried on 429 unless you allow more. After a 429 the per-host gap doubles.
- **Secret headers**: API keys go in an encrypted input field, are never written to the output, and are dropped if a redirect leaves the original host. Query values named like `api_key` or `token` are shown as `***` in the output.
- **Safe by design**: private, local and cloud metadata addresses are refused on every connection and every redirect, so the Actor cannot be pointed at internal networks.

### Input examples

Plain list of GET requests:

```json
{ "requests": ["https://httpbin.org/get", "https://jsonplaceholder.typicode.com/todos/1"] }
```

Mixed requests with a shared header and secret key:

```json
{
  "requests": [
    { "url": "https://api.example.com/v1/search", "queryParams": { "q": "coffee", "limit": 50 } },
    { "url": "https://api.example.com/v1/items", "method": "POST", "jsonBody": { "name": "test" }, "label": "create" },
    "curl https://api.example.com/v1/me -H 'Accept: application/json'"
  ],
  "headers": { "Accept": "application/json" },
  "secretHeaders": "Authorization: Bearer YOUR_TOKEN"
}
```

One request per row, with fields picked out:

```json
{
  "urlTemplate": "https://jsonplaceholder.typicode.com/todos/{{id}}",
  "rows": [{ "id": 1 }, { "id": 2 }, { "id": 3 }],
  "extractFields": { "title": "title", "done": "completed" }
}
```

Paginated API into one row per item:

```json
{
  "requests": ["https://api.example.com/v1/products?limit=100"],
  "splitArrayPath": "data",
  "nextUrlPath": "links.next",
  "maxPagesPerRequest": 50
}
```

Run with an empty input `{}` to see a demo against jsonplaceholder.typicode.com, a free fake API for testing.

### Output example

```json
{
  "index": 3,
  "label": null,
  "page": 1,
  "method": "GET",
  "url": "https://jsonplaceholder.typicode.com/todos/1",
  "finalUrl": "https://jsonplaceholder.typicode.com/todos/1",
  "status": 200,
  "ok": true,
  "contentType": "application/json; charset=utf-8",
  "durationMs": 83,
  "attempts": 1,
  "redirects": [],
  "row": { "id": 1 },
  "fields": { "id": 1, "title": "delectus aut autem" },
  "json": { "userId": 1, "id": 1, "title": "delectus aut autem", "completed": false },
  "error": null,
  "charged": true
}
```

### Pricing

Pay per request: **$2.00 per 1,000 requests** that get a response from the server (any status code, including 4xx and 5xx). Each pagination page counts as one request. Timeouts, network errors, refused addresses and invalid input rows are free. Set a maximum cost per run in Apify and the Actor stops exactly at that limit.

### Calling it from Clay, n8n, Make or code

Start a run with the Apify API (`POST https://api.apify.com/v2/acts/joesimo~http-request/run-sync-get-dataset-items`) or the Apify integration in your tool, pass the input JSON above, and read the dataset items. For many calls, put them all in one run: it is faster and cheaper than one run per call.

### Good to know

- No proxy and no browser: requests go straight from Apify servers with a descriptive User-Agent (you can set your own `user-agent` header). Sites that block data center IPs or need JavaScript will not work.
- Bodies over `maxBodyKb` (default 2 MB) are cut and marked `truncated`.
- Only call APIs and pages you are allowed to use, and follow each API's terms and rate limits. Use `delayPerHostMs` and `concurrency` to stay inside them.
- No login flows and no captcha solving. If an API needs a key, add it in Secret headers.

### Related Actors

- [Broken Link Checker](https://apify.com/joesimo/broken-link-checker) to crawl a site and check every link
- [Sitemap Extractor](https://apify.com/joesimo/sitemap-extractor) for every URL of a site with optional status checks
- [DNS Lookup](https://apify.com/joesimo/dns-lookup) for bulk DNS records

# Actor input Schema

## `requests` (type: `array`):

One entry per request. Each entry can be a URL string, a curl command copied from your browser or API docs, or an object like {"url": "https://api.example.com/items", "method": "POST", "headers": {"X-Key": "..."}, "queryParams": {"page": 1}, "jsonBody": {"name": "test"}, "label": "my label"}. Use body for a raw text body.

## `urls` (type: `array`):

Optional quick list of URLs. Each one is sent with the method, headers and body below.

## `urlTemplate` (type: `string`):

Build one request per row. Use {{field}} or {{nested.field}} placeholders, for example https://api.example.com/users/{{id}}?country={{country}}. Values are URL encoded. Placeholders also work in headers, query parameters and bodies.

## `rows` (type: `array`):

Objects that fill the URL template, one request per row, for example \[{"id": 1}, {"id": 2}]. A row is echoed back in the output so you can match results to your sheet or CRM.

## `bodyTemplate` (type: `string`):

Optional body for template rows, with {{field}} placeholders. A body that starts with { or \[ is sent as JSON and values are JSON escaped.

## `method` (type: `string`):

Used when a request does not set its own method. Requests with a body default to POST.

## `headers` (type: `object`):

Headers sent with every request, for example {"Accept": "application/json"}. A request's own headers win. Put API keys in Secret headers instead.

## `secretHeaders` (type: `string`):

Headers that hold API keys or tokens, one per line as Name: value (for example Authorization: Bearer YOUR_TOKEN). Stored encrypted by Apify, never written to the output, and dropped when a redirect leaves the original host.

## `queryParams` (type: `object`):

Query parameters added to every URL, for example {"limit": 100}.

## `jsonBody` (type: `object`):

JSON body sent with every request that has no body of its own (POST, PUT, PATCH, DELETE).

## `body` (type: `string`):

Raw text body sent with every request that has no body of its own. Ignored when JSON body is set.

## `responseFormat` (type: `string`):

How to save the response body.

## `extractFields` (type: `object`):

Pick values out of JSON responses into a fields column, as name: path pairs, for example {"title": "data.title", "firstTag": "data.tags\[0]"}. With Split array path, paths are read from each array element.

## `splitArrayPath` (type: `string`):

Path to an array in the JSON response, for example data.items. Each element becomes its own dataset row (still one charged request). Leave empty to keep one row per response.

## `includeHeaders` (type: `boolean`):

Save response headers (Set-Cookie is never saved).

## `includeRowInOutput` (type: `boolean`):

Copy each template row into the output row, so results can be joined back to your data.

## `maxBodyKb` (type: `integer`):

Bodies larger than this are cut and marked truncated.

## `nextUrlPath` (type: `string`):

Path in the JSON response that holds the next page URL (or a cursor if you set Cursor parameter), for example links.next or meta.next_cursor. Each page is one request.

## `cursorParam` (type: `string`):

If the next page path holds a cursor instead of a URL, the query parameter to put it in, for example cursor or page_token.

## `followLinkHeader` (type: `boolean`):

Follow pagination from the standard Link response header (GitHub style APIs).

## `maxPagesPerRequest` (type: `integer`):

Page limit for each starting request when pagination is on. Default 10.

## `concurrency` (type: `integer`):

Requests in flight at the same time.

## `delayPerHostMs` (type: `integer`):

Minimum gap between requests to the same host. Raise it to respect an API's rate limit. After a 429 the gap doubles automatically.

## `timeoutSecs` (type: `integer`):

Time limit for each attempt.

## `maxRetries` (type: `integer`):

Retries on timeouts, network errors, 429 and 5xx, honoring Retry-After. POST and PATCH are retried only on 429 unless the next option is on.

## `retryNonIdempotent` (type: `boolean`):

Also retry POST and PATCH after timeouts and 5xx. Only switch on if repeating the call is safe.

## `followRedirects` (type: `boolean`):

Follow 3xx redirects (up to 10). The chain is saved in redirects.

## Actor input object example

```json
{
  "requests": [
    "https://jsonplaceholder.typicode.com/posts/1",
    {
      "url": "https://jsonplaceholder.typicode.com/posts",
      "method": "POST",
      "jsonBody": {
        "title": "Hello",
        "userId": 1
      },
      "label": "create post"
    }
  ],
  "responseFormat": "auto",
  "includeHeaders": true,
  "includeRowInOutput": true,
  "maxBodyKb": 2048,
  "followLinkHeader": false,
  "concurrency": 5,
  "delayPerHostMs": 100,
  "timeoutSecs": 30,
  "maxRetries": 2,
  "retryNonIdempotent": false,
  "followRedirects": true
}
```

# Actor output Schema

## `results` (type: `string`):

One item per response, plus free rows for failed or invalid requests.

## `runSummary` (type: `string`):

JSON summary: responses by status class, failures, retries, rate limits, stop reason.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "requests": [
        "https://jsonplaceholder.typicode.com/posts/1",
        {
            "url": "https://jsonplaceholder.typicode.com/posts",
            "method": "POST",
            "jsonBody": {
                "title": "Hello",
                "userId": 1
            },
            "label": "create post"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("joesimo/http-request").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "requests": [
        "https://jsonplaceholder.typicode.com/posts/1",
        {
            "url": "https://jsonplaceholder.typicode.com/posts",
            "method": "POST",
            "jsonBody": {
                "title": "Hello",
                "userId": 1,
            },
            "label": "create post",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("joesimo/http-request").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "requests": [
    "https://jsonplaceholder.typicode.com/posts/1",
    {
      "url": "https://jsonplaceholder.typicode.com/posts",
      "method": "POST",
      "jsonBody": {
        "title": "Hello",
        "userId": 1
      },
      "label": "create post"
    }
  ]
}' |
apify call joesimo/http-request --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,joesimo/http-request"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/h7uYX3BB4RPsE93vq/builds/Uw68dWO4oyvxMygFr/openapi.json
