> ## 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.

# Troubleshooting Agent Analytics

> Diagnose sources that receive nothing, deliveries that fail, records that are dropped and numbers that look wrong, by symptom and by drop reason.

Start with **Check now** in the setup wizard. It reads the newest delivery for the source and names the most likely cause when half or more of its records were dropped for the same reason.

For connector-specific issues, see the troubleshooting section of each [connector page](https://docs.usequotable.com/agent-analytics/getting-started.md#choose-a-connector).

## The source receives nothing

The status stays **Waiting for the first delivery**.

> [accordion] Check the endpoint URL
>
> Each source has its own endpoint. CloudFront sources use the URL ending in `/firehose`, Google Cloud CDN sources the one ending in `/pubsub`, and every other push connector the one ending in `/events`. Copy it again from the wizard.

> [accordion] Send a test delivery
>
> Run the `curl` command from the wizard. If it gets `202`, the endpoint and token work, and the problem is on the platform side: the drain or job is disabled, filtered too narrowly, or not attached.

> [accordion] Check the platform's own delivery log
>
> Most platforms show failed deliveries and the HTTP status they got. Match it against [HTTP errors](#http-errors).

## Deliveries arrive, but no AI agents

The status is **Connected, waiting for the first agent visit**.

This is normal on a site with little traffic: the source turns active on the first recognized AI agent request. If it persists:

* Confirm the user agent field is included in your logs. Without it, nothing can be recognized.
* Look at `not_ai_agent` in a test delivery's response. A high count with a real crawler user agent means the field is missing or renamed.
* Check that the agent is in the [registry](https://docs.usequotable.com/agent-analytics/overview.md#recognized-ai-agents). Unknown bots aren't stored.

## HTTP errors

| Status | Meaning | Fix |
| - | - | - |
| `400` | Nothing in the body could be parsed | Send JSON, a JSON array or NDJSON. |
| `401` | Token missing, wrong or rotated | Send `Authorization: Bearer <current token>`. Tokens are never accepted in the query string. |
| `404` | Wrong source ID, or the source is disconnected | Copy the endpoint again from **Connected sources**. A disconnected source can't be reopened; connect the connector again to get a new endpoint and token. |
| `413` | More than 5 MB or 1,000 records in one delivery | Lower the platform's batch size. |
| `415` | Compression other than gzip | Use gzip or none. |
| `429` with `rate_limited` | More than 600 deliveries in 5 minutes for the source (6,000 for Google Cloud CDN and Cloudflare Worker sources) | Send larger, less frequent batches, or update the Cloudflare Worker to the latest version, which batches. Wait for `Retry-After`. |
| `429` with `quota_exceeded` | Today's quota for the source is used up | Wait for midnight UTC, or ask about a higher limit. |
| `503` | A temporary failure stored nothing | Retry with backoff. Platforms do this automatically. |

## Records are dropped

Every delivery response lists drops by reason. Here's what each one means and what to do:

| Reason | Common cause | Fix |
| - | - | - |
| `not_ai_agent` | Human traffic | Nothing. This is expected and free. |
| `host_mismatch` | The logs are for a different domain than the source | Filter logs to your domain, or connect the other domain as its own source. Subdomains of the source's domain are accepted. |
| `excluded_path` | Admin, auth, private, framework or static-asset paths | Nothing. These are never stored. |
| `timestamp_out_of_range` | A backfill older than seven days, or a wrong clock or timezone | Only send recent logs. Check timestamps carry a timezone or are UTC. |
| `invalid_record` | A required field is missing, or the record isn't JSON | Check `host` and `path` (or your platform's equivalents) are included. |
| `not_http_traffic` | Build or function output in a Vercel drain | Select request log sources only. |
| `environment_filtered` | Preview or branch deploy traffic | Restrict the drain to production, or opt into previews (Vercel). |
| `project_mismatch` | A Vercel drain covering a project other than the mapped one | Select only the mapped project. |
| `quota_exceeded` | The source's daily limit, or the workspace's monthly allowance, was reached during the delivery | See [Quotas](https://docs.usequotable.com/agent-analytics/getting-started.md#quotas). |

## Numbers look wrong

> [accordion] Every request is unverified
>
> The logs don't carry the visitor's IP, or they carry a proxy's IP. Include the client IP field, and connect the edge closest to visitors (your CDN rather than your origin). Agents whose provider publishes no ranges or hostnames are always unverified. See [How verification works](https://docs.usequotable.com/agent-analytics/how-verification-works.md).

> [accordion] Many requests show as spoofed
>
> The IP in your logs isn't the visitor's. A request behind a proxy appears to come from the proxy, which is outside the crawler's published ranges. Use the client IP your CDN reports.

> [accordion] Response time shows 0 or is missing
>
> The connector doesn't provide duration (Cloudflare Worker), or your records don't include it. Sources without duration are left out of latency.

> [accordion] Two sources show different numbers for the same site
>
> Each source counts what its platform sees. A CDN sees cached hits; an origin only sees cache misses. Connect one source per layer you want to measure, and compare rates only between sources with the same fields.

> [accordion] A page I expected is missing
>
> Paths are stored without the query string, with trailing slashes removed and ID-like segments replaced by `:id` or `:token`. Static assets and admin paths aren't stored. Search with a path prefix in the filters.

> [accordion] Counts stopped at a round number
>
> The source hit its daily limit, and events beyond it are dropped until midnight UTC. Or the workspace used its monthly allowance, and events are dropped until the 1st of next month (UTC). See [Quotas](https://docs.usequotable.com/agent-analytics/getting-started.md#quotas).

## The source shows "delayed"

A source that used to deliver hasn't delivered for an hour. Check that the drain or job is still enabled and still points at the same endpoint, and that the token wasn't rotated without updating the platform. The next successful delivery makes it active again.

## Still stuck

Contact support with the source's domain, connector, the token prefix shown under **Connected sources** (never the full token), and the response body of a test delivery.

## Next steps

> [card] [FAQ](https://docs.usequotable.com/agent-analytics/faq.md)
>
> Short answers to common questions.

> [card] [Custom HTTP reference](https://docs.usequotable.com/agent-analytics/connectors/custom-http.md)
>
> The full delivery contract.


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