Batch digests

A queue collects events your systems push and sends them as one message per batch, so a hundred deploy notifications become one digest. You create the queue once, push events as they happen, and the evaluator sends each batch when its window closes. Creating and changing queues needs the queues:write scope (admins and up); pushing events needs queues:write too; reading needs queues:read. Credits are spent per batch when it is sent, never when events are pushed. Each batch costs the queue’s credit_cost, 1 unless you set it.

Create a queue

curl -X POST https://api.lithoblocks.com/v1/queues \
  -H "Authorization: Bearer $LITHOBLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy digest",
    "template_id": "6b1e…",
    "execution_mode": "fixed_interval",
    "execution_config": { "interval_minutes": 60 },
    "destination": { "channel_id": "C0AS92CQ04D" },
    "aggregation_config": {
      "item_mapping": { "service": "$.service", "version": "$.version" },
      "aggregate_mapping": { "count": { "strategy": "count_events" } }
    }
  }'

Field	Required	Meaning
`name`	yes	Up to 255 characters.
`description`	no	Up to 2000 characters.
`template_id`	yes	The template each batch is rendered with.
`execution_mode`	yes	`fixed_interval`, `rolling_window` or `fixed_volume`; see below.
`execution_config`	yes	The mode’s settings, with exactly the keys the mode takes.
`destination`	yes	Exactly one of `channel_id`, `recipient_email` or `recipient_slack_id`.
`aggregation_config`	no	How a batch’s events become the template’s `data`; see below.
`credit_cost`	no	Credits per batch, 1 to 100. Default 1.
`is_active`	no	Default `true`. `false` creates the queue paused.

The response is 201 with the queue, including pending_event_count (events waiting in the open batch) and, on GET /v1/queues/{id}, an active_batch summary.

Execution modes

Mode	`execution_config`	Behaviour
`fixed_interval`	`{ "interval_minutes": 60 }`	The batch closes a fixed time after its first event.
`rolling_window`	`{ "window_minutes": 30 }`	Every new event pushes the close out again; a quiet spell of `window_minutes` ends the batch.
`fixed_volume`	`{ "event_threshold": 10, "max_wait_minutes": 120 }`	The batch is ready as soon as it holds `event_threshold` events, and closes anyway `max_wait_minutes` after its first event.

The keys are exact. Anything else, threshold or interval for instance, is refused with 400 and a message naming the accepted keys.

Aggregation

item_mapping builds one item per event from paths into the event ($.field or field), placed under items, or under the key you name in items_key. aggregate_mapping computes values across the batch, each entry { "strategy": …, "field": "$.path" }:

Strategy	Result	Needs `field`
`first`, `last`	The value from the first or last event.	yes
`min`, `max`, `sum`	Over the numeric values.	yes
`count_events`	The number of events in the batch.	no
`most_frequent`	The value that occurs most often.	yes
`any_true`, `all_true`	Whether any, or every, value is truthy.	yes

The template then receives, for example, { "items": [{ "service": "api", "version": "1.2" }, …], "count": 7 }. Without an aggregation_config, the template receives { "items": [event, …] } with the events as pushed.

Tiers

Which modes and how many active queues your organization may have, and how many events it may push in 24 hours, depend on its subscription tier. Over any of these lines the API answers 403 with code: "tier_limit" and a message naming the tier and the limit.

Tier	Active queues	Events per day	Modes
Free	not available
Builder	3	500	`fixed_interval`
Team	10	5,000	all three
Business	50	50,000	all three
Enterprise	999	999,999	all three

Push events

curl -X POST https://api.lithoblocks.com/v1/queues/{id}/events \
  -H "Authorization: Bearer $LITHOBLOCKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-run-1234" \
  -d '{ "events": [{ "service": "api", "version": "1.2.0" }] }'

Up to 100 events per call, each any JSON object. The events join the queue’s open batch, or start one if nothing is collecting. The response is 202:

{
  "batch_id": "b7e4…",
  "event_ids": ["e1a0…"],
  "batch_status": "collecting",
  "window_end": "2026-09-06T14:12:00.000Z",
  "event_count": 4
}

batch_status is ready when a fixed_volume queue has just reached its threshold, otherwise collecting; window_end is when the batch will close if nothing else happens. Send an Idempotency-Key so a retried push cannot count the same events twice: the same key and body within 24 hours replays the original response. A paused queue (is_active: false) refuses events with 409 and code: "invalid_state". The queue-ingest edge function that accepted events before this route is deprecated. It still answers for existing integrations but takes no new features; move to POST /v1/queues/{id}/events.

Watch and steer

Do	Call
List queues, with `pending_event_count`	`GET /v1/queues`, optionally `?is_active=true` or `false`
Read one, with its open `active_batch`	`GET /v1/queues/{id}`
Change settings, pause or resume	`PATCH /v1/queues/{id}`; `is_active` pauses and resumes
See what the template would receive right now	`POST /v1/queues/{id}/preview`, returns `{ event_count, aggregated_data }` without sending or spending
Send the open batch now	`POST /v1/queues/{id}/flush`, the batch goes on the next evaluator tick
Discard pending events	`POST /v1/queues/{id}/drop-pending`, returns how many were dropped
Batch history	`GET /v1/queues/{id}/batches`, newest first, `?status=` filters
Event history	`GET /v1/queues/{id}/events`, newest first, `?status=` and `?batch_id=` filter
Every send attempt	`GET /v1/queue-executions`, `?queue_id=`, `?scheduled_message_id=` and `?result=` filter
Delete	`DELETE /v1/queues/{id}`

Batch statuses are collecting, ready, processing, sent and failed; a failed batch carries error_message, typically insufficient_credits or no_slack_connection. Event statuses are pending, aggregated (sent as part of a batch), expired and dropped. A failed batch leaves its events pending; drop them with drop-pending once you have dealt with the cause. Executions record each attempt the evaluator made for your organization, batch and scheduled message alike: execution_type (batch_send, scheduled_send, constraint_check, manual_send), result (success, failed, deferred), events_processed, processing_time_ms and error_message. Deleting a queue is refused with 409 while events are pending; flush or drop them first. Its batches and executions go with it.

Getting started

Templates

Interactive

Modals

Queues and scheduling

Advanced

Best practices

Examples

Troubleshooting

Architecture

Create a queue

Execution modes

Aggregation

Tiers

Push events

Watch and steer

​Create a queue

​Execution modes

​Aggregation

​Tiers

​Push events

​Watch and steer

Create a queue

Execution modes

Aggregation

Tiers

Push events

Watch and steer