Batch Fetch

POST/api/v1/idap/batch

Overview

Fetch up to 100 resources in a single request. Accepts mixed resource types — you can fetch businesses, domains, and contacts all in one call. Resources are grouped by type internally and fetched with efficient batch queries (not N+1).

This is ideal for loading dashboard views or board cards that each hold an idap:// reference.

Request Body

refsarrayrequired

List of idap:// references to fetch. Maximum 100 refs per request. Can mix resource types.

Example:

[
  "idap://businesses/abc123",
  "idap://domains/def456",
  "idap://emails/ghi789"
]

fieldsstring

Comma-separated field projection applied to all resources.

Example: "name,email,phone,enrichment_score"

includestring

Comma-separated related resource types to include for each resource.

Example: "emails,phones"

Response

resultsobject

Successfully resolved resources, keyed by their idap:// reference string. Each value is a full IDAP resource with idap_ref, resource_type, resource_id, flags, data, and optionally related.

errorsobject

Error messages for refs that could not be resolved, keyed by the idap:// reference string.

Common errors:

• "resource_not_found" — resource doesn't exist or belongs to another tenant
• "Use GET /idap/media/{media_id} for media resources" — media refs not supported in batch
• "Invalid IDAP ref — ..." — malformed reference string

Example Request

cURL

curl -X POST "https://spideriq.ai/api/v1/idap/batch" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [
      "idap://businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "idap://businesses/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "idap://emails/em41l-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
      "idap://media/screenshot-456"
    ],
    "fields": "name,email,address,verified"
  }'

Python

import httpx

response = httpx.post(
    "https://spideriq.ai/api/v1/idap/batch",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "refs": [
            "idap://businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "idap://businesses/b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "idap://emails/em41l-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
        ],
        "fields": "name,email,address",
    },
)
data = response.json()

for ref, resource in data["results"].items():
    print(f"{ref}: {resource['data'].get('name', resource['data'].get('address', ''))}")

for ref, error in data["errors"].items():
    print(f"ERROR {ref}: {error}")

Response Example

{
  "results": {
    "idap://businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "idap_ref": "idap://businesses/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resource_type": "businesses",
      "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenant_id": "cli_b3q656h2cg8j9o6z",
      "created_at": "2026-03-15T10:00:00Z",
      "modified_at": "2026-04-11T10:32:00Z",
      "flags": ["qualified"],
      "data": {
        "name": "Mario's Pizzeria",
        "email": "info@mariospizzeria.com",
        "address": "123 Brickell Ave, Miami FL"
      }
    },
    "idap://businesses/b2c3d4e5-f6a7-8901-bcde-f12345678901": {
      "idap_ref": "idap://businesses/b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "resource_type": "businesses",
      "resource_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "tenant_id": "cli_b3q656h2cg8j9o6z",
      "created_at": "2026-04-01T08:00:00Z",
      "modified_at": "2026-04-11T14:20:00Z",
      "flags": ["new"],
      "data": {
        "name": "Bella Italia",
        "email": "contact@bellaitalia.com",
        "address": "456 Ocean Dr, Miami FL"
      }
    },
    "idap://emails/em41l-1d2e-3f4a-5b6c-7d8e9f0a1b2c": {
      "idap_ref": "idap://emails/em41l-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
      "resource_type": "emails",
      "resource_id": "em41l-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
      "tenant_id": "cli_b3q656h2cg8j9o6z",
      "created_at": "2026-04-10T12:00:00Z",
      "modified_at": "2026-04-10T12:05:00Z",
      "flags": [],
      "data": {
        "address": "info@mariospizzeria.com",
        "verified": true
      }
    }
  },
  "errors": {
    "idap://media/screenshot-456": "Use GET /idap/media/{media_id} for media resources"
  }
}

Limits

Constraint	Value
Max refs per request	100
Media refs	Not supported — use Media Proxy instead
Cross-tenant refs	Return resource_not_found (no existence leakage)

Performance

Resources are grouped by type and fetched with batch IN() queries — not individual lookups. Flags are also resolved in batch. A 100-ref request typically completes in under 200ms.