Back to API Reference

Bulk Operations API

Efficient batch processing for multiple entities in a single request. Process up to 100 entities per request.

Bulk Operations

POST/api/v1/bulk

Perform batch operations on multiple entities efficiently. Supports GET, EXISTS, and COUNT operations.

Request Body Parameters

ParameterTypeRequiredDescription
operationstringYesOperation type: get, exists, count
entity_typestringYesEntity type: companies, people, investors
identifiersarrayYesArray of entity IDs (max 100)
fieldsarrayNoSpecific fields to return (for GET operation)

Bulk GET Operation

Retrieve multiple entities in a single request with optional field selection.

Example Request

cURL
curl -X POST "https://mentibus.xyz/api/v1/bulk" \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "get",
    "entity_type": "companies",
    "identifiers": [1, 2, 3, 4, 5],
    "fields": ["id", "name", "slug", "overview", "website"]
  }'

Example Response

200 OK
{
  "success": true,
  "data": {
    "operation": "get",
    "entity_type": "companies",
    "requested_count": 5,
    "results": {
      "companies": [
        {
          "id": 1,
          "name": "OpenAI",
          "slug": "openai",
          "overview": "AI research and deployment company...",
          "website": "https://openai.com"
        },
        {
          "id": 2,
          "name": "Anthropic",
          "slug": "anthropic",
          "overview": "AI safety company...",
          "website": "https://anthropic.com"
        }
      ]
    },
    "metadata": {
      "processed_at": "2024-01-15T10:30:00Z",
      "processing_time_ms": 45
    }
  },
  "message": "Bulk get operation completed for 5 companies"
}

Bulk EXISTS Operation

Check existence of multiple entities without retrieving full data.

Example Request

cURL
curl -X POST "https://mentibus.xyz/api/v1/bulk" \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "exists",
    "entity_type": "people",
    "identifiers": [1, 2, 999, 1000, 5]
  }'

Example Response

200 OK
{
  "success": true,
  "data": {
    "operation": "exists",
    "entity_type": "people",
    "requested_count": 5,
    "results": {
      "people": [
        {
          "id": 1,
          "exists": true
        },
        {
          "id": 2,
          "exists": true
        },
        {
          "id": 999,
          "exists": false
        },
        {
          "id": 1000,
          "exists": false
        },
        {
          "id": 5,
          "exists": true
        }
      ]
    }
  },
  "message": "Bulk exists operation completed for 5 people"
}

Bulk COUNT Operation

Get count of existing entities from a list of identifiers.

Example Request

cURL
curl -X POST "https://mentibus.xyz/api/v1/bulk" \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "count",
    "entity_type": "investors",
    "identifiers": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  }'

Example Response

200 OK
{
  "success": true,
  "data": {
    "operation": "count",
    "entity_type": "investors",
    "requested_count": 10,
    "results": {
      "investors": {
        "count": 7
      }
    }
  },
  "message": "Bulk count operation completed for 10 investors"
}

Error Handling

Bulk operations include individual error tracking for each entity type.

Example Error Response

200 OK (Partial Success)
{
  "success": true,
  "data": {
    "operation": "get",
    "entity_type": "companies",
    "requested_count": 3,
    "results": {
      "companies": [
        {
          "id": 1,
          "name": "OpenAI",
          "slug": "openai"
        }
      ]
    },
    "errors": [
      {
        "entity_type": "companies",
        "error": "Failed to fetch companies"
      }
    ]
  }
}

Limitations

Request Limit

Maximum 100 identifiers per request

Rate Limiting

Bulk operations count as multiple API calls for rate limiting

Timeout

Large bulk requests may timeout. Consider smaller batches for better performance

Common Use Cases

Data Synchronization

Check which entities exist before attempting updates or creating relationships.

operation: "exists"

Batch Data Retrieval

Retrieve multiple entities efficiently with only the fields you need.

operation: "get", fields: ["id", "name"]

Analytics Preparation

Count entities for analytics without retrieving full data.

operation: "count"

Cache Warming

Pre-load frequently accessed entities into your application cache.

operation: "get", fields: ["id", "slug", "name"]