Signals

Ingest Events (Batch)

Send multiple signal events in a single API call for efficient bulk ingestion.

#Overview

Send up to 100 signal events in a single API call. Batch ingestion is more efficient than sending individual events and is recommended when you have multiple events to submit at once.

#Endpoint

POST /v1/events/batch

#Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_your_api_key_here

#Request Body

Field Type Required Description
events array Yes Array of event objects (max 100)
events[].signal string Yes The signal slug
events[].version number | "latest" No Schema version to use. Defaults to "latest"
events[].identity object Yes The CRM object this event relates to
events[].identity.type string Yes Object type: account, contact, deal, lead, or a custom type
events[].identity.id string Yes The object's ID in your CRM
events[].data object No Arbitrary JSON payload with event-specific data
events[].timestamp string No ISO 8601 timestamp. Defaults to current time
events[].reference string No An optional client-provided identifier echoed back in the response. Useful for correlating requests with results.

#Example Request

curl -X POST https://api.bigmind.ai/v1/events/batch \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
      "events": [
        {
          "signal": "visited-documentation-page",
          "identity": { "type": "account", "id": "001ABC000000123" },
          "data": { "page": "/docs/quickstart" },
          "reference": "evt-001"
        },
        {
          "signal": "visited-documentation-page",
          "identity": { "type": "account", "id": "001ABC000000456" },
          "data": { "page": "/docs/api-reference" },
          "reference": "evt-002"
        }
      ]
    }'

#Example Response

{
  "success": true,
  "data": [
    {
      "id": "7871725b-d50d-4cac-ae89-c4c1617767fc",
      "signal_id": "sig_bFyqj0qg",
      "schema_version": null,
      "status": "pending",
      "reference": "evt-001"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "signal_id": "sig_bFyqj0qg",
      "schema_version": null,
      "status": "pending",
      "reference": "evt-002"
    }
  ]
}

#Limits

  • Maximum 100 events per batch request
  • All events in a batch must reference valid, active signals
  • Events can reference different signals within the same batch

#Rate Limiting

Rate limits are enforced per signal within the batch. Each event counts toward the rate limit of its respective signal. Events for different signals are tracked independently.

Signal Type Rate Limit
Event 100 requests/min per signal
Metric 1,000 requests/min per signal
State 30 requests/min per signal

Rate limit information is included in the response headers:

  • X-RateLimit-Limit — Maximum requests allowed per minute (highest across all signals in the batch)
  • X-RateLimit-Remaining — Lowest remaining requests across all signals in the batch
  • X-RateLimit-Reset — ISO 8601 timestamp when the next rate limit window resets

Partial Rate Limiting

If some events in the batch exceed their signal's rate limit while others don't, the request will still return 200 OK. Successfully ingested events appear in data, while rate-limited events are listed in a separate top-level rate_limited array. If you provided a reference, it will be included so you can identify which events to retry:

{
  "success": true,
  "data": [
    {
      "id": "7871725b-d50d-4cac-ae89-c4c1617767fc",
      "signal_id": "sig_bFyqj0qg",
      "schema_version": null,
      "status": "pending",
      "reference": "evt-001"
    }
  ],
  "rate_limited": [
    { "signal_id": "sig_bFyqj0qg", "reference": "evt-002" }
  ]
}

#Error Responses

400 Bad Request

Returned when the events array is missing, empty, or exceeds the limit.

{
  "success": false,
  "error": "events array is required and must not be empty"
}
{
  "success": false,
  "error": "Maximum 100 events per batch"
}

404 Not Found

Returned when one or more signal slugs do not match any active signal.

{
  "success": false,
  "error": "Signals not found: my-invalid-signal"
}

429 Too Many Requests

Returned when all events in the batch exceed their signal's rate limit. Check the X-RateLimit-Reset header for when to retry.

{
  "success": false,
  "error": "Rate limit exceeded for all events in batch"
}
Updated 3/16/2026