Batch requests

Beta POST /v1/batch

POST /v1/batch

Up to 100 GET requests in one call; each result is a full envelope, charged as if called alone (cached repeats and failures free). Items run concurrently, each counts toward the rate limit, and a failed item never fails the others. Send an Idempotency-Key header to retry a batch safely: the first answer is replayed and nothing is charged twice.

Cost: The sum of each sub-request's charge
Status: Beta. Built and tested against recorded responses; the shape may still gain fields.
Cache: Not cached.
Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

Name	Type	Required	Description	In
`requests`	array	yes	List of {"path": "/v1/...", "params": {...}}.	body

Example request#

Set your key in the environment first (see Authentication).

curl

curl -X POST "https://api.socialscrape.io/v1/batch" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"requests":[{"path":"/v1/github/user","params":{"handle":"torvalds"}},{"path":"/v1/github/user","params":{"handle":"gaearon"}}]}'

Python

import os
import requests

payload = {
    "requests": [
        {
            "path": "/v1/github/user",
            "params": {
                "handle": "torvalds",
            },
        },
        {
            "path": "/v1/github/user",
            "params": {
                "handle": "gaearon",
            },
        },
    ],
}
res = requests.post(
    "https://api.socialscrape.io/v1/batch",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    json=payload,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])

TypeScript

const res = await fetch("https://api.socialscrape.io/v1/batch", {
  method: "POST",
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY!, "content-type": "application/json" },
  body: JSON.stringify({"requests": [{"path": "/v1/github/user", "params": {"handle": "torvalds"}}, {"path": "/v1/github/user", "params": {"handle": "gaearon"}}]}),
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}

Example response#

This is a sample with illustrative values. Status 200.

{
  "ok": true,
  "credits_charged": 2,
  "credits_remaining": 4998,
  "cached": false,
  "cached_at": null,
  "request_id": "req_48cebd0a43eb45183d397192",
  "data": {
    "object": "batch",
    "results": [
      {
        "path": "/v1/github/user",
        "status": 200,
        "response": {
          "ok": true,
          "credits_charged": 1,
          "credits_remaining": 4999,
          "cached": false,
          "cached_at": null,
          "request_id": "req_a1b2c3d4e5f6a1b2c3d4e5f6",
          "data": {
            "object": "profile",
            "platform": "github",
            "id": "1024025",
            "handle": "torvalds",
            "name": "Linus Torvalds",
            "url": "https://github.com/torvalds",
            "kind": "person"
          },
          "cursor": null,
          "has_more": null
        }
      },
      {
        "path": "/v1/github/user",
        "status": 200,
        "response": {
          "ok": true,
          "credits_charged": 1,
          "credits_remaining": 4998,
          "cached": false,
          "cached_at": null,
          "request_id": "req_f6e5d4c3b2a1f6e5d4c3b2a1",
          "data": {
            "object": "profile",
            "platform": "github",
            "id": "810438",
            "handle": "gaearon",
            "name": "Dan Abramov",
            "url": "https://github.com/gaearon",
            "kind": "person"
          },
          "cursor": null,
          "has_more": null
        }
      }
    ]
  },
  "cursor": null,
  "has_more": null
}

Response#

A BatchResult object in data.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

Code	HTTP	Retry	Meaning
`invalid_params`	400	no	A parameter is missing, unknown or has the wrong type.

Every request can also fail with the account and platform errors listed on the Errors page.

Get started

Guides

API reference

Resources