SignalResearch up to ten profiles per batch
Send one to ten profile lookup objects in a single authenticated request and handle each result independently.
| Parameter | Type | Required | Description |
|---|---|---|---|
items | array<object> | Yes | 1–10 profile lookup objects. Entire array validated before any item is processed. |
Request a batch
POST /api/v1/batch expects a JSON object with an items array. Each item supports the same platform, handle, mode, and freshness fields as a single lookup. All items are validated before processing; one malformed item rejects the whole request without spending credits.
curl "$SIGNALSHELF_BASE_URL/api/v1/batch" \
-H "Content-Type: application/json" \
-H "x-api-key: $SIGNALSHELF_API_KEY" \
--data '{"items":[{"platform":"bluesky","handle":"bsky.app","mode":"live","freshness":"24h"},{"platform":"bluesky","handle":"example.bsky.social","mode":"live","freshness":"24h"}]}'// Run in a server environment. Never expose the key in client-side code.
const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/v1/batch`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.SIGNALSHELF_API_KEY,
},
body: JSON.stringify({"items":[{"platform":"bluesky","handle":"bsky.app","mode":"live","freshness":"24h"},{"platform":"bluesky","handle":"example.bsky.social","mode":"live","freshness":"24h"}]}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error?.code}: ${result.error?.message}`);
console.log(result);# Server-side Python; install requests if needed.
import os
import requests
response = requests.post(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/batch",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
json={'items': [{'platform': 'bluesky', 'handle': 'bsky.app', 'mode': 'live', 'freshness': '24h'}, {'platform': 'bluesky', 'handle': 'example.bsky.social', 'mode': 'live', 'freshness': '24h'}]},
timeout=45,
)
result = response.json()
response.raise_for_status()
print(result)A successful HTTP response can include a failed item
After input validation, lookups are processed in array order. The HTTP 200 response contains results with success true or false. Always inspect each item, rather than treating the outer status as proof that every profile succeeded. This abbreviated response illustrates a cached success and an unavailable profile.
{
"results": [
{
"success": true,
"data": {
"platform": "bluesky",
"handle": "bsky.app",
"sample": false
},
"meta": {
"cache": "HIT",
"credits_charged": 0,
"event_id": "example-event-id"
}
},
{
"success": false,
"handle": "example.bsky.social",
"error": {
"code": "PROFILE_NOT_FOUND",
"message": "Public profile not found. No credits charged.",
"status": 404
}
}
],
"credits_charged": 0
}Credits and retries
The outer credits_charged is the sum of successful fresh items. Failed, sample, and cached items use zero. A batch is not an all-or-nothing transaction: earlier successes remain charged if a later item fails. Retry only failed items when practical. A repeated live request can trigger another charge; there is no client-supplied idempotency key.
Size and timing
The maximum is ten items and the request-body limit is 32 KB. The beta processes items sequentially, so batch duration can exceed a single lookup. Set a client timeout appropriate to your batch size and avoid automatic full-batch retries after a transport timeout; inspect usage first because the server may have completed some items.