> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/insights/settings/vercel-agent-analytics.md). # Vercel Agent Analytics Connect your Vercel project to AirOps to track AI bot traffic. AirOps automatically provisions a **Vercel Log Drain** when you install the integration, classifies AI bot visits (ChatGPT, Claude, Perplexity, Google, and more), and surfaces insights in your Agent Analytics dashboard. *** ### Prerequisites * An active **AirOps** account with Agent Analytics enabled * A **Vercel Pro or Enterprise** account (Log Drains are not available on Hobby plans) * A **Vercel project** serving your website on a custom domain * A **Brand Kit** in AirOps whose domain matches your Vercel deployment domain (configurable under Context > Brand Kits > Brand URL) If you're not sure whether your brand kit is set up correctly, check with your AirOps Customer Success contact before installing. *** ### Step 1: Install AirOps from the Vercel Marketplace 1. Open the install URL: [`https://vercel.com/integrations/airops-agent-analytics/new`](https://vercel.com/integrations/airops-agent-analytics/new) 2. Vercel shows a team picker. Select the **Vercel team** that owns the project you want to track. 3. Vercel displays the **Install AirOps Agent Analytics** screen. Under "Select which projects the integration will have access to", choose **Specific Projects** and pick only the project(s) that serve your tracked brand site. 4. Click **Install**. {% hint style="info" %} We strongly recommend **Specific Projects** over **All Projects**. "All Projects" gives the integration access to every project under your Vercel team, including unrelated ones (marketing sites, internal tools, preview deployments). AirOps filters out logs that don't match your brand kit domain before storing them, but they still generate Vercel drain egress (approximately $0.50/GB) on your invoice. Picking only the brand-site project keeps Vercel costs predictable and avoids streaming traffic that will be discarded. {% endhint %} *** ### Step 2: Connect to your AirOps Workspace After authorizing in Vercel, you'll be redirected back to AirOps. * If your AirOps account has access to **one workspace**, the integration connects automatically. * If you have access to **multiple workspaces**, a picker appears. Select the workspace you want this Vercel integration to attach to. AirOps automatically provisions a Vercel Log Drain on your selected team. No manual configuration of endpoint URLs, signature secrets, or Bearer headers is required. You'll be redirected to the AirOps Agent Analytics integration page on Vercel, confirming the install is complete. *** ### Step 3: Verify the Connection In AirOps, navigate to **Insights > Settings > General** for any brand kit and scroll to the **Connected Integrations** section. You should see a **Vercel** row with: * A green **Connected** badge * The name of your connected Vercel team * An **Uninstall in Vercel** action Data begins flowing as soon as your site receives traffic from an AI bot. At low traffic volumes, Vercel batches records and delivers them every **30 to 60 seconds**. {% hint style="warning" %} Vercel's **Test** button (in the Drains settings on Vercel's side) only sends synthetic logs without request data. A passing Test does **not** mean real traffic will appear in AirOps; it only confirms the endpoint is reachable. Real agent traffic arrives once an AI bot makes a request to your site that matches your configured projects. {% endhint %} *** ### Troubleshooting | Symptom | Likely Cause | Fix | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Vercel row shows **Connected** but no data appears in Insights Traffic | Your brand kit's domain doesn't match your Vercel deployment domain | In AirOps, open Brand Kit settings and confirm the brand URL matches the domain your Vercel project actually serves (for example, `acme.com` not `www.acme.com` if your site is served at `acme.com`). | | Vercel emails you "drain errored" | AirOps endpoint returned 4xx/5xx for more than 50 deliveries in an hour, or more than 80% of deliveries in an hour | Contact AirOps Customer Success. We can diagnose from server logs. | | Drain shows as "active" but no rows appear after 5 minutes | You tested with Vercel's auto-generated deployment URL (for example, `-.vercel.app`) | Vercel's Deployment Protection on Pro plans returns 401 to bots on these URLs. Use your project's public alias or a custom domain instead. | | Test button passes but no real data ever appears | You hit paths that 404 on a static deploy | 404s on static-only deploys are served from Vercel's edge cache without invoking the drain. Visit a known-good path that actually exists in your deployment. | | Bytes column shows 0 for some requests | Cached static hits do not include `responseByteSize` | This is expected on Vercel-cached static assets. Other metrics (status, user-agent, timing) are unaffected. | | You removed the integration in Vercel but AirOps still shows **Connected** | Page is showing stale state | Hard-refresh the AirOps page (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows). The Vercel uninstall webhook is asynchronous and takes a few seconds to land. | *** ### Plan Requirements Vercel Log Drains are available on **Vercel Pro and Enterprise** plans only. Hobby plans cannot create drains; if your team is on Hobby, you will need to upgrade before installing. Vercel bills drain egress at approximately $0.50 per GB streamed, charged on your Vercel invoice. For low-traffic sites this is typically less than $1 per month. For high-traffic sites, reduce cost two ways: scope the install to **Specific Projects** on the brand-site project only (see Step 1), and in Vercel's per-environment settings start with Production only and exclude preview deployments. *** ### Security and least-privilege setup #### Permissions required to install **On Vercel:** any user with the **Member** role on your Vercel team can install the integration. Owner is not required. Setting up integrations is part of the Member role's standard responsibilities ([Vercel access roles](https://vercel.com/docs/rbac/access-roles)). **On AirOps:** the user completing the install must be signed in to AirOps and a member of the target workspace, and any AirOps role works. #### Dedicated service-style user AirOps does not have a separate machine-identity primitive distinct from a user, but the integration is designed so the installing user is only the install-time actor and is not the runtime principal. You can satisfy least-privilege expectations by treating a dedicated user account as a service-account proxy: 1. Invite a named, dedicated user (for example, `vercel-airops@yourcompany.com`) into your AirOps workspace. Use the lowest-privilege role your workspace offers. 2. Sign in as that user once and complete the OAuth install. 3. After the install completes, that user has no runtime authority. The integration continues to authenticate via the workspace API token described below. You can remove the user from the workspace afterwards if your security policy requires it; the integration keeps working. The same pattern applies on the Vercel side: a dedicated Vercel user with the Member role can do the install and then be left as a dormant team member. #### Runtime authentication After install, no user session is involved in any drain delivery. Authentication on each delivery is two-layered: * **HMAC-SHA1 signature** of the request body, keyed by a per-installation drain secret generated by AirOps at install time. Vercel sends the signature in the `x-vercel-signature` header on every delivery. * **Bearer token** in the `Authorization` header. The token is your **workspace's AirOps API key**, written into the drain configuration during install. Both factors are at the workspace level, not the user level. The installing user is recorded in AirOps audit metadata only. #### Token rotation The workspace API key is rotatable in-app under **Account > Workspace > API Key** (requires AirOps workspace admin role). Two things to understand before rotating: * The Vercel drain has the previous token baked into its outbound `Authorization` header. After rotation, the drain will start failing authentication until the integration is reinstalled from Vercel (which writes the new token into a new drain). * The same workspace API key authenticates other AirOps APIs (Public API, MCP server, SDK). Rotating it affects all of those, not only Vercel. If rotation cadence is part of your compliance policy, the safe sequence is: rotate the AirOps token, then immediately reinstall the Vercel integration from Vercel's marketplace listing. #### What this integration does not do * It does not request scopes on your Vercel account beyond what is required to create and manage a log drain on the selected team. It cannot read project source, environment variables, or deployment logs outside of the drain's request stream. * It does not write back to your Vercel account on an ongoing basis. After the initial drain provisioning, AirOps only receives data from Vercel; it does not call Vercel's API again unless you reinstall or disconnect. If your security review needs additional detail, contact AirOps Customer Success and we can walk your team through the data flow at the implementation level. *** ### Disconnecting To remove the Vercel integration: 1. In AirOps, open **Insights > Settings > General > Connected Integrations**. 2. Click **Uninstall in Vercel** in the Vercel row. This takes you to your Vercel team's integrations page. 3. Find the AirOps integration and click **Remove**. Confirm. 4. AirOps marks the integration as **Disconnected** on your next page refresh. Your historical Vercel data stays in AirOps after disconnecting. To resume tracking, click **Reinstall on Vercel** from the same row. *** ### What AirOps Tracks Once connected, AirOps automatically: * **Ingests all Vercel-served requests:** page views, assets, API calls * **Classifies AI bot traffic:** identifies visits from ChatGPT, Claude, Google, Perplexity, Meta, Apple, Bing, Bytedance, Common Crawl, and others * **Categorizes crawl behavior:** distinguishes between AI training crawlers (GPTBot, ClaudeBot, etc.), AI search fetches (PerplexityBot, OAI-SearchBot, etc.), and user-initiated AI browsing (ChatGPT-User, Claude-User, etc.) * **Surfaces analytics:** traffic breakdowns, bot-vs-human ratios, and crawl trends in your dashboard --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.airops.com/insights/settings/vercel-agent-analytics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.