Ctrlk
HomeSign In
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Vercel Agent Analytics

Connect your Vercel project to AirOps to track AI bot traffic via Vercel Log Drains.

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

  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.

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.

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.

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.

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, <project>-<hash>.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).

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

Last updated

Was this helpful?