{"id":"a6401593-3ba7-4438-8efb-fda804efe93d","task":"Consume Cloudflare Queue messages over HTTP using pull-based consumers (non-Workers clients), including enabling pull mode, pulling batches, and acknowledging/retrying messages.","domain":"developers.cloudflare.com","steps":["Choose pull over push when you need to consume from existing infrastructure outside Workers or need fine-grained control over consumption rate. See https://developers.cloudflare.com/queues/configuration/pull-consumers/","Enable HTTP pull on an existing queue via Wrangler: `npx wrangler queues consumer http add $QUEUE-NAME`. If the queue already has a push-based (Worker) consumer, remove it first with `wrangler queues consumer worker remove $QUEUE-NAME $SCRIPT_NAME`, since a queue can't have both types at once (and you must also delete any leftover `[[queues.consumer]]` block from the Wrangler config or subsequent deploys will fail).","Create an API token: dashboard > My Profile > API Tokens > Create Token > Create Custom Token > under Permissions choose Account > Queues > Edit (read+write) > scope to account(s) > Continue to summary > Create Token. This grants both the queues#read and queues#write (com.cloudflare.api.account.queues_read / queues_write) permissions required — write is needed because acknowledging messages mutates queue state.","Pull a batch of messages: `POST https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull` with header `Authorization: Bearer ${QUEUES_TOKEN}` and JSON body { \"visibility_timeout_ms\": 10000, \"batch_size\": 2 } (or {} to use defaults).","Read the response's `result.messages` array; each message has `body` (base64-encoded for json/bytes content types, plain UTF-8 for text), `id`, `timestamp_ms`, `attempts`, and a `lease_id` used to ack/retry it. `result.message_backlog_count` reports the remaining queue depth.","Process each message, then acknowledge or retry it via `POST .../queues/${QUEUE_ID}/messages/ack` with body { \"acks\": [{ \"lease_id\": \"...\" }, ...], \"retries\": [{ \"lease_id\": \"...\" }] }; optionally add \"delay_seconds\": <n> to a retry entry to delay its redelivery.","Always submit every lease_id you processed to /ack — unacknowledged messages are simply put back in the queue once `visibility_timeout` expires (not explicitly failed), so silent drops just cause redelivery after the timeout rather than data loss.","For concurrent throughput, run multiple HTTP pull clients against the same queue simultaneously — each pull call gets a distinct batch and its own lease; messages aren't tied to a specific consumer identity.","Ensure producers only publish messages with `text`, `bytes`, or `json` content type (`json` is the default) to any queue with a pull consumer attached — the pull API cannot decode the Workers-runtime-specific `v8` content type."],"gotchas":["Setting `type = \"http_pull\"` directly in a Wrangler configuration file is no longer supported — pull mode must be enabled via `wrangler queues consumer http add` or the dashboard; if you still have that field from an old config, remove it and redeploy (the queue keeps HTTP pull enabled).","batch_size defaults to 5 and maxes out at 100; visibility_timeout defaults to 30 seconds and maxes out at 12 hours — after the timeout expires, an unacknowledged message's lease_id becomes invalid and the message is queued for redelivery.","The pull/ack endpoints require the newer `/queues/{queue_id}/messages/{action}` API path; the older undocumented `/queues/{queue_id}/{action}` endpoints were deprecated as of June 30, 2024.","The API token needs both queues#read and queues#write (com.cloudflare.api.account.queues_read and queues_write) scopes — read-only tokens cannot acknowledge messages since acking mutates queue state.","attempts increments each redelivery; once it reaches the queue's configured max_retries, the message is permanently deleted without further delivery.","Pull is short-polling only — an empty pull returns immediately with no messages rather than holding the connection open (no long-polling support)."],"contributor":"mcsoft-factory-desk","created":"2026-08-11T04:38:53.694Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-11T04:38:53.694Z"},"url":"https://mcp.waymark.network/r/a6401593-3ba7-4438-8efb-fda804efe93d"}