--- name: vercel-usage-and-spend description: "Every weekday: what this Vercel billing cycle has cost so far, how much included credit is left, the projected total, and which resource is driving it. Use when the user asks for this, or when it runs on a schedule." --- # Vercel usage and spend this billing cycle Every weekday: what this Vercel billing cycle has cost so far, how much included credit is left, the projected total, and which resource is driving it. Most surprises on a Vercel invoice were visible on the Usage page two weeks earlier: a crawler walking every preview URL, an image route with no cache, a function that started running three times longer. The page is good; it just only helps people who open it. The agent reads the cycle's charges every weekday, compares spend so far with the included credit and with an even pace, and names the resource that moved, whether function invocations, Active CPU, Fast Origin Transfer or build minutes. When the pace points past the credit, the card says by roughly how much, early enough for developers and finance to act. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - A Vercel token for a team member with the Owner, Member, Developer, Billing or Security role (the roles the charges endpoint accepts) in `VERCEL_TOKEN`, with the team ID. - Or the Vercel MCP server or connector, signed in as such a member. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Pull the cycle's charges** (Vercel): `GET /v1/billing/charges?from=&to=&teamId=` streams one JSON line per charge and day in the FOCUS 1.3 format (`ServiceName`, `SkuId`, `ChargeCategory`, `ConsumedQuantity`, `ConsumedUnit`, `BilledCost`, `ChargePeriodStart`, and `Tags` with the project ID and name). With the Vercel MCP server, use its billing charges tool. 2. **Group by resource**: Keep rows with `ChargeCategory` of `Usage` and sum `BilledCost` and `ConsumedQuantity` per `ServiceName`: Function Invocations, Active CPU, Provisioned Memory, Fast Origin Transfer, Fast Data Transfer and CDN Requests beyond the Flat Rate CDN capacity, Image Optimization and build minutes. Keep daily totals for the cycle-to-date line, and leave out seat, add-on and Flat Rate CDN tier charges. 3. **Compare with the credit and the pace**: Subtract spend from the plan's included usage credit (every Pro team gets $20 a month, applied from the first unit; it expires at the end of the cycle). Project the cycle total from the daily average and flag a projected overage of more than 10%. 4. **Find what moved**: Compare each resource's last 7 days with the 7 before. A jump of 50% or more in invocations, Active CPU or origin transfer usually means a crawler, a retry loop or a cache miss; name the project from `Tags`, and point to Observability for the route. 5. **Report**: Spend so far, credit left, the projected total, and the top resources by cost with their weekly change. ## Route B: the browser ### What you need - Signed in to Vercel as a member of the team with a role that can open Usage and Settings > Billing (Owner, Member or Billing; Viewer seats cannot see billing). If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://vercel.com/dashboard. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open the team's Usage page**: Select the team in the team switcher, then click **Usage** in the sidebar. Leave the billing cycle dropdown on the current cycle; the overview shows each resource's usage so far and its projected cost for the cycle. 2. **Read the credit**: At the top of the overview, read spend so far against the included credit ($20 a month on Pro). Open **Settings > Billing** once to confirm the plan, the credit and any Flat Rate CDN tier, and keep those in the prompt. 3. **Go through the sections**: Scroll the **Functions**, **CDN**, **Builds** and **Image Optimization** sections. For each metric note the quantity, the billed amount and the projection. Switch the view from **Count** to **Project** to see which project drives a metric. 4. **Find what moved**: Change the billing cycle dropdown to **Last 30 days** and read each chart: compare the last 7 days with the 7 before by eye. A step up of 50% or more in invocations, Active CPU or origin transfer is the one to name, with its project from the Project view. 5. **Report**: Spend so far, credit left, the projected cycle total and overage, the top three resources by cost with their weekly change, and the likely cause of any jump. Note: The Usage page already projects cost per resource, so the browser route needs less arithmetic than the API one; the week-over-week comparison is read off charts and is approximate. Usage data on the page lags by up to a few hours. ## The report - **Spend this cycle** so far, and the included credit left. - **Projected total** for the cycle at the current pace. - **By resource**: function invocations, Active CPU, data transfer, build minutes and anything else above a dollar, with the week-over-week change. - **What moved**: the resource and project behind any jump. - One line on what to change if an overage is coming. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "vercel-usage-and-spend/", "item_key": "vercel-usage-and-spend", "project": "Acme", "source": "Vercel usage and spend this billing cycle skill", "kind": "metric", "title": "$14.82 of the $20 credit used, overage likely", "metric": { "label": "Usage spend this cycle", "value": 14.82, "prefix": "$", "better": "lower", "period_start": "", "period_end": "" }, "glance": [ { "type": "Progress", "props": { "label": "Included credit used", "value": 74, "text": "$14.82 of $20.00", "tone": "warn" } }, { "type": "Grid", "props": { "columns": 3 }, "children": [ { "type": "Stat", "props": { "label": "Invocations", "value": "10.0M", "delta": 58, "better": "lower" } }, { "type": "Stat", "props": { "label": "Data transfer", "value": 1.03, "unit": "TB", "delta": 12, "better": "lower" } }, { "type": "Stat", "props": { "label": "Build minutes", "value": 86, "delta": -5, "better": "lower" } } ] } ], "widget": [ { "type": "Table", "props": { "columns": [ "Resource", "Used", "Billed", "vs last week" ], "align": [ "left", "right", "right", "right" ], "rows": [ [ "Function invocations", "10.0M", "$5.40", "+58%" ], [ "Fast Data Transfer", "1.03 TB", "$4.12", "+12%" ], [ "Active CPU", "24.2 h", "$3.10", "+41%" ], [ "Build minutes", "86 min", "$1.20", "-5%" ], [ "Edge Requests", "10.5M", "$1.00", "+9%" ] ] } }, { "type": "Callout", "props": { "text": "At this pace the cycle ends near $27.80, about $7.80 past the credit. Invocations jumped after Oct 12, mostly /api/og on acme-web.", "tone": "warn" } } ], "size": "md" } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters). ## Run it on a schedule Suggested: Weekdays at 9:30 (`30 9 * * 1-5`). From cron, with the agent signed in on that machine: ```bash 30 9 * * 1-5 claude -p "Run the vercel-usage-and-spend skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/vercel-usage-and-spend#schedule Source: https://briefkin.dev/skills/vercel-usage-and-spend