Skip to main content
POST
/
api
/
ingest
POST /api/ingest
curl --request POST \
  --url https://sluice.sh/api/api/ingest

Documentation Index

Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt

Use this file to discover all available pages before exploring further.

Accepts a batch of normalized events from the SDK or agent. This is the primary data ingestion endpoint — all job, worker, and queue data enters Sluice through this endpoint.

​
Authentication

API key via Authorization: Bearer sk_... header.

​
Request body

{
  "events": [
    {
      "type": "job_state_change",
      "timestamp": "2026-02-27T10:30:00.000Z",
      "framework": "celery",
      "connectionId": "550e8400-e29b-41d4-a716-446655440000",
      "job": {
        "externalId": "abc123-def456",
        "name": "app.tasks.send_email",
        "queue": "default",
        "state": "completed",
        "previousState": "active",
        "workerId": "celery@worker-1",
        "attempt": 1,
        "createdAt": "2026-02-27T10:29:55.000Z",
        "startedAt": "2026-02-27T10:29:56.000Z",
        "completedAt": "2026-02-27T10:30:00.000Z"
      }
    }
  ]
}

​
Event fields

FieldTypeRequiredDescription
typestringYesEvent type identifier (e.g., job_state_change, worker_state_change, queue_snapshot).
timestampstringYesISO 8601 datetime.
frameworkstringYesOne of celery, bullmq, sidekiq.
connectionIdstringYesUUID of the connection. Must match the authenticated API key’s connection.
jobobjectNoJob event payload. Present for job-related events.
workerobjectNoWorker event payload. Present for worker-related events.
queueobjectNoQueue snapshot payload. Present for queue metrics.
Exactly one of job, worker, or queue should be present per event.

​
Job payload

FieldTypeRequiredDescription
externalIdstringYesFramework-native job ID (Celery task UUID). Max 512 chars.
namestringYesTask/job type name (e.g., app.tasks.send_email). Max 1024 chars.
queuestringNoQueue name. Max 255 chars.
statestringYesUnified state: unknown, queued, scheduled, active, completed, failed, retrying, cancelled.
previousStatestringNoPrevious unified state.
workerIdstringNoWorker identifier. Max 512 chars.
attemptintegerNoCurrent attempt number (1-indexed).
maxRetriesintegerNoConfigured retry limit.
progressnumberNoProgress value between 0.0 and 1.0.
errorstringNoError message on failure. Max 10,000 chars.
stacktracestringNoFull traceback on failure. Max 50,000 chars.
createdAtstringNoISO 8601 — when the job was dispatched.
startedAtstringNoISO 8601 — when execution began.
completedAtstringNoISO 8601 — when execution finished.
extensionsobjectNoFramework-specific fields that don’t map to the common model.

​
Worker payload

FieldTypeRequiredDescription
externalIdstringYesFramework-native worker ID (e.g., celery@worker-1).
hostnamestringYesWorker hostname.
pidintegerNoWorker process ID.
statestringYesOne of online, busy, idle, offline, heartbeat.
concurrencyintegerNoMax concurrent jobs.
activeJobsintegerNoCurrently processing count.
queuesstring[]NoQueues this worker consumes.
metadataobjectNoFramework-specific metadata (software versions, pool type, etc.).

​
Queue payload

FieldTypeRequiredDescription
namestringYesQueue name. Max 255 chars.
depthintegerYesCurrent number of pending jobs.
consumersintegerNoNumber of active consumers.

​
Limits

  • Maximum 1,000 events per request.
  • Maximum 5 MB request body.
  • Free tier: 10,000 events per day. Resets at midnight UTC.

​
Response

{
  "accepted": 42,
  "rejected": 0,
  "skipped": 3,
  "truncated": 0,
  "usage": {
    "used": 8042,
    "limit": 10000,
    "remaining": 1958,
    "resetAt": "2026-02-28T00:00:00.000Z"
  }
}

​
Response fields

FieldTypeDescription
acceptedintegerNumber of events successfully processed.
rejectedintegerNumber of events that failed validation or processing.
skippedintegerNumber of duplicate events that were skipped.
truncatedintegerNumber of events dropped because the daily limit was reached mid-batch.
usageobjectCurrent usage counters for the day.