POST/v1/extract/batch

Extract metadata from multiple URLs in a single request.

Request Body

Name	Type	Required	Default	Description
`urls`	`string[]`		-	Array of URLs to extract metadata from
`cache`	`boolean`		`true`	Whether to use cached results if available

Batch Limits by Plan

Plan	URLs per Request
Free	5
Starter	10
Pro	25
Business	50
Enterprise	100

Request Example

curl -X POST "https://api.katsau.com/v1/extract/batch" \
  -H "Authorization: Bearer ks_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com",
      "https://twitter.com",
      "https://dev.to"
    ],
    "cache": true
  }'

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "url": "https://github.com",
        "success": true,
        "data": {
          "title": "GitHub: Let's build from here",
          "description": "GitHub is where over 100 million developers...",
          "image": "https://github.githubassets.com/...",
          "open_graph": { ... },
          "twitter": { ... }
        },
        "cache_hit": true
      },
      {
        "url": "https://twitter.com",
        "success": true,
        "data": { ... },
        "cache_hit": false
      },
      {
        "url": "https://invalid-url.xyz",
        "success": false,
        "error": {
          "code": "TARGET_UNREACHABLE",
          "message": "Could not reach the target URL"
        }
      }
    ],
    "summary": {
      "total": 3,
      "successful": 2,
      "failed": 1
    }
  },
  "meta": {
    "request_id": "req_abc123xyz",
    "response_time_ms": 1245
  }
}

Handling Partial Failures

Batch requests may have partial failures. The overall request succeeds (HTTP 200), but individual URLs may fail. Check the success field for each result.

const { data } = await response.json();

for (const result of data.results) {
  if (result.success) {
    console.log(`✓ ${result.url}: ${result.data.title}`);
  } else {
    console.log(`✗ ${result.url}: ${result.error.message}`);
  }
}

console.log(`Summary: ${data.summary.successful}/${data.summary.total} successful`);

Error Codes

Code	HTTP	Description
`BATCH_TOO_LARGE`	400	Too many URLs for your plan
`INVALID_BODY`	400	Request body is not valid JSON
`INVALID_URL`	400	One or more URLs are invalid