Basic ToolBatch1 credit

get_batch_results

Retrieve paginated results for a batch_scrape job. Submit the batch once, then poll this endpoint with the returned batchId to check status and page through results as they complete.

Use Cases

Poll a Running Batch

Check job status and pull the pages that have finished while the rest of the batch is still running.

Page Through Large Jobs

Walk results 25 at a time (up to 100 per page) instead of holding an entire batch in memory.

Resume After a Restart

The batchId outlives your process — a worker that crashes can pick up exactly where it left off.

Cheap Status Checks

At 1 credit per call, polling costs a fraction of re-running the batch you already paid for.

Endpoint

POST/api/v1/tools/get_batch_results

Auth Required

1 req/s on Free plan

1 credit

Parameters

batchId comes from the batch_scrape response — this tool never starts a job, it only reads one back.

Name	Type	Required	Default	Description
batchId	string	Required	-	The batch job identifier returned by `batch_scrape`. Example: batch_1700000000000_abc123def
page	number	Optional	1	Page number to retrieve (1-based). Example: 1
limit	number	Optional	25	Results per page (1-100). Example: 50

Request Examples

cURL

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/get_batch_results \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batchId": "batch_1700000000000_abc123def",
    "page": 1,
    "limit": 25
  }'

TypeScript

getBatchResults.tsTypescript

// npm install crawlforge-sdk
import { CrawlForge } from 'crawlforge-sdk';

const client = new CrawlForge({ apiKey: process.env.CRAWLFORGE_API_KEY });

// Read total_pages from the first response, then loop — one fewer call than
// incrementing until you get an empty array.
const first = await client.getBatchResults({
  batchId: 'batch_1700000000000_abc123def',
  page: 1,
  limit: 25,
});

// result.data is untyped in crawlforge-sdk 0.1 — its shape is the Response Example below.
type BatchPage = {
  batch_id: string;
  status: string;
  total: number;
  total_pages: number;
  results: { url: string; status: string }[];
};
const { batch_id, status, total, total_pages, results } = first.data as BatchPage;
const all = [...results];

for (let page = 2; page <= total_pages; page++) {
  const next = await client.getBatchResults({ batchId: batch_id, page, limit: 25 });
  all.push(...(next.data as BatchPage).results);
}

console.log('Batch ' + status + ': ' + all.length + ' of ' + total + ' results');
console.log('Credits remaining:', first.creditsRemaining);

Python

get_batch_results.pyPython

# pip install crawlforge
from crawlforge import CrawlForge

client = CrawlForge()  # reads CRAWLFORGE_API_KEY

# Read total_pages from the first response, then loop — one fewer call than
# incrementing until you get an empty list.
first = client.get_batch_results(batchId='batch_1700000000000_abc123def', page=1, limit=25)

# result.data is a plain dict — its shape is the Response Example below.
batch = first.data
all_results = list(batch['results'])

for page in range(2, batch['total_pages'] + 1):
    nxt = client.get_batch_results(batchId=batch['batch_id'], page=page, limit=25)
    all_results.extend(nxt.data['results'])

print(f"Batch {batch['status']}: {len(all_results)} of {batch['total']} results")
print(f"Credits remaining: {first.credits_remaining}")

Response Example

200 OK96ms

{
  "success": true,
  "data": {
    "batch_id": "batch_1700000000000_abc123def",
    "status": "completed",
    "page": 1,
    "limit": 25,
    "total": 3,
    "total_pages": 1,
    "results": [
      {
        "url": "https://example.com/page-1",
        "status": "completed",
        "data": {
          "title": "Example page 1"
        }
      },
      {
        "url": "https://example.com/page-2",
        "status": "completed",
        "data": {
          "title": "Example page 2"
        }
      }
    ]
  },
  "credits_used": 1,
  "credits_remaining": 999,
  "processing_time": 96
}

Field Descriptions

data.batch_idThe batch job you queried, echoed back

data.statusStatus of the batch as a whole

data.totalTotal number of results across every page

data.total_pagesHow many pages exist at the current `limit`

data.resultsOne entry per URL in this page, each with its own per-URL `status`

credits_usedCredits deducted for this request (1 per retrieval)

credits_remainingYour remaining credit balance

Error Handling

Invalid Input (400 Bad Request)

batchId is empty, page is below 1, or limit falls outside the 1-100 range.

Retrieval Failed (500 Internal Server Error)

The batch could not be read back — most often an unknown or expired batchId. Credits are not deducted for a failed retrieval.

Insufficient Credits (402 Payment Required)

Your account doesn't have enough credits. Purchase more credits or upgrade your plan.

Rate Limit Exceeded (429 Too Many Requests)

You've exceeded your plan's rate limit. Wait a moment or upgrade your plan for higher limits.

Pro Tip:

Read total_pages from the first response and loop until you've fetched them all, rather than incrementing page until you get an empty array — it costs one fewer call per batch.