> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Worker

> Report AI agent requests from a fail-open Cloudflare Worker on any Cloudflare plan, without changing or delaying your responses.

The Worker connector works on every Cloudflare plan with Workers. It sits on your route, passes each request to your origin unchanged, and, when the request comes from an AI agent, reports it to Quotable **after** the response is on its way.

> [!NOTE]
>
> If your zone is on Cloudflare Enterprise, use [Cloudflare Logpush](https://docs.usequotable.com/agent-analytics/connectors/cloudflare-logpush.md) instead. Logpush is out of band and measures response time; the Worker runs on every request of its route.

## How the Worker protects your site

* **Fail open.** Telemetry is sent with `ctx.waitUntil()` after the origin response is returned. A failure is swallowed and never changes the response.
* **No body access.** The Worker never reads or clones the response body.
* **Batched.** Agent requests are collected for up to 2 seconds, or until 50 are waiting, and sent as one report. One report per batch instead of one per request keeps a busy site well inside the delivery limit.
* **Bounded.** Each report has a time budget (3 seconds by default, 5 at most).
* **Circuit breaker.** After 5 consecutive failed reports, the Worker stops reporting for 60 seconds, so an outage on our side costs you nothing but skipped reports. Authentication errors (`4xx`) don't open the breaker.
* **One hostname.** The Worker only reports requests for the hostname you bind it to.

## What it measures

Every field except **response time**. Response size is read from the `content-length` header, so streamed responses without it report no size.

The Worker only reports requests whose user agent matches one of the [recognized AI agents](https://docs.usequotable.com/agent-analytics/overview.md#recognized-ai-agents). The list is built into each Worker version, so download the latest version to pick up agents added later.

## Set up

**1. Create the source in Quotable**

In **Agent Analytics**, select **Connect source**, choose **Cloudflare Worker** and select **Generate credentials**. Copy the token, the endpoint URL and the `AGENT_ANALYTICS_HOSTNAME` value.

**2. Download the Worker**

Select **Download Worker template**. You get a single module file, `quotable-agent-analytics-worker-v1.3.0.mjs`.

**3. Configure Wrangler**

Create a `wrangler.toml` next to the file. Replace the hostname, zone and endpoint with your own values:

```toml wrangler.toml theme={"system"}
# Quotable Agent Analytics — Cloudflare Worker connector v1.3.0
name = "quotable-agent-analytics-example-com"
main = "quotable-agent-analytics-worker-v1.3.0.mjs"
compatibility_date = "2026-09-01"

# zone_name is the registrable domain (shop.example.co.uk → example.co.uk);
# if your zone is a subdomain delegated to Cloudflare, set it to that zone.
routes = [
  { pattern = "example.com/*", zone_name = "example.com" },
]

[vars]
AGENT_ANALYTICS_ENDPOINT = "<your endpoint URL>"
AGENT_ANALYTICS_HOSTNAME = "example.com"
# Optional protections (defaults shown):
# AGENT_ANALYTICS_TIMEOUT_MS = "3000"
# AGENT_ANALYTICS_SAMPLE_RATE = "1"
# AGENT_ANALYTICS_BATCH_SIZE = "50"
# AGENT_ANALYTICS_FLUSH_MS = "2000"
```

**4. Store the token as a secret**

Never put the token in `wrangler.toml`. Store it as a Worker secret:

```bash theme={"system"}
npx wrangler secret put AGENT_ANALYTICS_TOKEN
```

Paste the `aa_live_…` token when prompted.

**5. Deploy**

```bash theme={"system"}
npx wrangler deploy
```

**6. Confirm delivery**

Run the self-test below, then select **Check now** in Quotable. The source turns active on the first AI agent request to your site.

## Settings

| Binding | Required | Description |
| - | - | - |
| `AGENT_ANALYTICS_ENDPOINT` | Yes | The endpoint URL from the wizard. |
| `AGENT_ANALYTICS_TOKEN` | Yes | The source token. Store it as a secret. |
| `AGENT_ANALYTICS_HOSTNAME` | Yes | The one hostname the Worker reports, for example `example.com`. Requests for other hostnames on the route are passed through without reporting. |
| `AGENT_ANALYTICS_TIMEOUT_MS` | No | Time budget per report, from `500` to `5000`. Default `3000`. |
| `AGENT_ANALYTICS_SAMPLE_RATE` | No | Share of agent requests reported, from `0` to `1`. Default `1` (all). |
| `AGENT_ANALYTICS_BATCH_SIZE` | No | Agent requests per report, from `1` to `500`. Default `50`. `1` sends every request on its own. |
| `AGENT_ANALYTICS_FLUSH_MS` | No | Longest a request waits for its batch, in milliseconds, from `0` to `10000`. Default `2000`. |

If one of the three required bindings is missing, the Worker passes traffic through and reports nothing.

## Volume limit

A Worker source accepts up to 6,000 reports per 5-minute window, about 20 per second. Version 1.2.0 and later send up to 50 agent requests per report, so the limit is far above what a single site's AI agent traffic produces. Earlier versions send one report per agent request; update to the latest version if you see `429` responses.

Batches are kept per Worker instance, in memory. If Cloudflare stops an instance before its batch is sent, that batch is lost; with the 2-second default this is rare. Above the limit, reports are refused with `429` and the circuit breaker pauses reporting. If that happens, set `AGENT_ANALYTICS_SAMPLE_RATE` below `1`, or use [Cloudflare Logpush](https://docs.usequotable.com/agent-analytics/connectors/cloudflare-logpush.md), which sends batches of up to 1,000 records.

## Self-test

Check that the token works and see which version is installed:

```bash theme={"system"}
curl -sS -X POST https://app.usequotable.com/api/agent-analytics/connectors/cloudflare-worker/self-test \
  -H "Authorization: Bearer aa_live_..." \
  -H "x-quotable-connector-version: 1.3.0"
```

```json theme={"system"}
{
  "ok": true,
  "source_id": "…",
  "hostname": "example.com",
  "status": "active",
  "installed_version": "1.3.0",
  "latest_version": "1.3.0",
  "upgrade_available": false,
  "last_delivery_at": "2026-10-01T09:12:44.000Z",
  "last_event_at": "2026-10-01T09:12:44.000Z",
  "rollback": "wrangler rollback"
}
```

The self-test stores nothing. It's limited to 30 calls per 5 minutes per IP address. A wrong, rotated or disconnected token returns `401`.

## Update or roll back

When `upgrade_available` is `true`, download the template again from the wizard, replace the module file, update `main` in `wrangler.toml` and run `npx wrangler deploy`. To go back to the previous deployment without downtime, run `npx wrangler rollback`.

## Rotate the token

1. Rotate the token in Quotable. The old token stops working immediately.
2. Run `npx wrangler secret put AGENT_ANALYTICS_TOKEN` with the new token.

Reports sent in between are refused with `401`. They don't open the circuit breaker.

## Disconnect

Remove the route or delete the Worker in Cloudflare, then disconnect the source in Quotable.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| No deliveries at all | A required binding is missing, or the hostname doesn't match | Check all three bindings. `AGENT_ANALYTICS_HOSTNAME` must equal the hostname in the browser, for example `www.example.com` versus `example.com`. |
| Deliveries but no agents | No AI agent has visited yet | Normal on a quiet site. Send a test delivery from the wizard to confirm the wiring. |
| Agent requests appear about 2 seconds late | Expected | Requests are batched for up to `AGENT_ANALYTICS_FLUSH_MS`. Set it to `0`, or the batch size to `1`, while testing. |
| `401` in the self-test | Token wrong, rotated or for another source | Put the current token in the Worker secret. |
| Gaps during busy periods | Over the delivery limit, so the breaker paused reporting | Update to the latest version, which batches. If gaps continue, lower the sample rate or switch to Logpush. |
| Response time is empty | Expected | The Worker can't measure origin time. Use Logpush if you need it. |

## Next steps

> [card] [Cloudflare Logpush](https://docs.usequotable.com/agent-analytics/connectors/cloudflare-logpush.md)
>
> The out-of-band option for Enterprise zones.

> [card] [How verification works](https://docs.usequotable.com/agent-analytics/how-verification-works.md)
>
> The Worker sends the visitor IP from `cf-connecting-ip` for verification.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.