Claude Admin API Implementation Guide: Connecting Usage Data to Engineering Delivery Metrics

TL;DR: Anthropic does not expose a single reporting surface for Claude Code usage. Aggregated Claude Code analytics, broader API usage and cost data, enterprise engagement analytics, and an OpenTelemetry integration are separate paths, each returning a different slice at a different grain. To prove return on investment (ROI), run a linear regression of a value delivery metric like story points completed against token spend, measured in dollars, and read the slope. Relationship recovery, linking AI sessions to the commits, pull requests, and tickets they produced, is the normalization step most teams underestimate. Identity resolution across version control, project management, and Claude is the easier half, and minware handles both before the regression runs.

Your chief financial officer (CFO) does not care how many lines of code Claude Code generated last month. They want to know whether those lines translated into completed roadmap items. Most engineering leaders trying to measure Claude ROI fall into the throughput trap, presenting pull request counts as proof of value while work queues at the review stage.

Connecting the Claude Admin API is how you move past that trap. This guide covers what the API returns, how to configure it securely, and how to normalize its output against version control and ticketing. It ends with the regression that produces a defensible answer for your next board review.

Choosing the right interface

Before writing a line of configuration, confirm which interface your pipeline needs. Teams frequently conflate the standard Claude API with the Admin API, which leads to mis-scoped credentials and missing attribution data.

Reporting surface	Primary purpose	Key type required	User attribution
Claude Code Analytics API	Per-developer Claude Code activity and cost	Admin API key (Console) or Analytics API key (Enterprise)	user_actor (email) or api_actor (api_key_name)
Usage and Cost API	Organization-wide token usage and cost	Admin API key	By API key, workspace, and model, no user dimension
Claude Enterprise Analytics API	Enterprise-wide engagement, adoption, cost, and usage across Claude products	Analytics API key	Per-user daily activity across chat, Claude Code, and other products
OpenTelemetry	Per-prompt, per-session telemetry	No API key, configured via managed settings	Per-session, fields configurable

The standard Claude API and the Admin API share a hostname but differ in namespace and credential. Both live under api.anthropic.com/v1, while the reporting endpoints sit under /v1/organizations/ and require an Admin API key, which is different from the standard Claude API key your applications use to call the model. A pipeline reading developer-level usage from the standard Claude API is reading the wrong surface.

Understanding what the API returns

The Admin API gives you programmatic access to historical usage and cost data, equivalent to the Usage and Cost pages in the Claude Console but queryable by your own analytics infrastructure.

Reading token spend for ROI analysis

Token spend in this context means dollar cost. Token consumption is a separate data point, and conflating the two produces ROI calculations that do not hold up to scrutiny.

Cost figures arrive as estimated cost in cents USD broken down by model. One qualifier matters when a spend figure carries weight in a claim: reported spend may be more or less than the amount actually paid for users on flat-rate plans such as Claude Pro. The API distinguishes these through a customer type field separating pay-as-you-go API usage from subscription usage.

That qualifier does not invalidate the metric. Reported spend remains the most consistent proxy for usage intensity, and it is the number you regress against delivery outcomes.

Attributing usage to individual developers

The Claude Code Analytics API returns per-user estimated costs and productivity metrics, free to every organization with Admin API access. It is not gated to Enterprise plans.

Attribution granularity is what makes this endpoint useful. Each record represents one user's activity for a single day, identified by email address, with token counts and estimated cost broken down by model. The broader Usage and Cost API groups by API key, workspace, model, and service tier, with no user dimension at all.

Email-based attribution matters more than it first appears, and it does not cover every record. Usage records identify each developer through an actor field that is either user_actor, carrying an email address for OAuth-authenticated usage, or api_actor, carrying only an api_key_name for API-key-authenticated usage. Email is the field your version control and ticketing systems also carry, which makes it the join key for OAuth-authenticated records.

Naming the data gaps and scope limits

The usage, cost, and analytics endpoints return aggregated metadata, with no raw prompt text. This is narrower than it sounds: the Compliance API content endpoints, under a separate scope, can read chats, files, and Claude Code session transcripts. Whether prompt text reaches your analytics layer through telemetry is configured entirely within your OpenTelemetry setup, where prompt text, tool details, and tool content are redacted by default and exported only if you explicitly enable them.

One scope limit deserves attention before you build anything. The Claude Code Analytics API only tracks Claude Code usage on the Claude API. Usage through Amazon Bedrock, Microsoft Foundry, Google Cloud, or Claude Platform on AWS is not included, and the Enterprise Analytics API carries the same limitation for Bedrock. If your organization runs Claude Code through one of those, confirm your reporting path before committing to the implementation below.

Configuring your integration

Most teams that have already rolled out Claude Code have not configured data collection against the Admin API. The integration is not automatic. Analytics data backfills when you connect, so a late start still gives you history. Telemetry only runs forward, which is the argument for setting it up early.

Creating your API key

Where you create the key depends on your organization type, and the two paths produce different credentials.

For a Claude Console organization, sign in as an organization admin, go to Settings then Admin keys, and click Create key. Name it descriptively, set an expiration, and create it. The secret begins with sk-ant-admin01- and is displayed only once before being permanently masked.

For a Claude Enterprise organization, the primary owner signs in at claude.ai, opens Organization settings then API, and creates a key from the Keys section. That secret begins with sk-ant-api01- instead.

One branch point matters before you write ingestion code. The endpoints in this guide sit under the Admin API and require an Admin API key from Claude Console. Claude Enterprise organizations use the Claude Enterprise Analytics API instead, under /v1/organizations/analytics/, with an Analytics API key created at claude.ai. The two key types are not interchangeable: an Admin API key cannot call the Claude Enterprise Analytics API, and an Analytics API key cannot call the Admin API. The regression methodology later in this guide applies either way, but the ingestion endpoints differ.

Store the secret in your secrets manager before closing the dialog. Keys are scoped to the organization in which they are created, so a company running both Claude Console and Claude Enterprise needs one key in each. Whichever key you hold, pass it in the x-api-key header on every request rather than embedding it in request bodies.

Choosing scopes

Scope selection depends on which key you created. Claude Console admin keys carry full access to every endpoint that accepts them, with no selectable scopes.

Claude Enterprise keys do offer scope selection, and scopes are fixed at creation, so adding one later means creating a new key. For spend and usage reporting, select read:analytics for the Analytics API and read:spend_limits for the Spend Limits API. Avoid granting write:spend_limits unless your pipeline explicitly needs to create or delete spend limit rules.

Securing key access

Admin API keys carry broad organizational access. Applying the Principle of Least Privilege (PoLP) here means granting the analytics pipeline read access and nothing else. Four controls matter before your first production ingestion run.

• Rotate keys on a fixed schedule. Set an expiration at creation. A 90-day rotation cycle is a reasonable starting point for an analytics key.
• Store secrets in a vault. Environment variables in shared continuous integration environments are readable by any process in that context. Use a dedicated secrets manager instead.
• Restrict key use to your analytics service account. If the key is compromised, its blast radius should be limited to read access on usage data.
• Log every API call that uses the key. An unexpected spike in Admin API calls is an early indicator of credential misuse.

Treat the data the key returns with the same care as the key itself. Token cost and consumption figures are per-developer records, so apply the access controls you would use for salary data.

For organizations that cannot share credentials externally, minware's on-premise ingest agent runs inside your environment and connects to source systems using your own credentials, so those keys never reach minware's infrastructure.

Working with the API output

The subsections below cover the endpoints, metadata structure, and timestamp handling you need before wiring the output into a normalization layer.

Querying the core usage endpoints

Two endpoints matter for delivery correlation, and they behave differently enough that the distinction shapes your ingestion loop. Both endpoints require an Admin API key. Claude Enterprise organizations read the equivalent data from the Claude Enterprise Analytics API under /v1/organizations/analytics/ instead.

The /v1/organizations/usage_report/messages endpoint reports organization-wide token consumption, with breakdowns by model, workspace, and service tier. It supports daily, hourly, and minute-level buckets. A single request covers up to 31 buckets at daily granularity.

The /v1/organizations/usage_report/claude_code endpoint reports per-developer Claude Code activity. It takes a single date and returns metrics for this single day only, with cursor-based pagination inside each day. A year of Claude Code history is 365 requests, one per day, regardless of how you batch elsewhere.

Mapping team and member metadata

Records identify developers by email address. Mapping those to your internal team hierarchy requires a lookup table connecting each address to a canonical contributor record in your data warehouse.

If you use SCIM 2.0 for user provisioning, your identity provider already maintains the mapping between directory identities and Claude accounts. Export that mapping as part of your ingestion pipeline setup.

For organizations not using SCIM, build the mapping from the member list in your admin console and maintain it as an export that feeds your normalization layer.

Aligning timestamps across systems

The analytics endpoints return daily aggregates in UTC, where the date parameter represents UTC midnight for that day. Your version control commits carry local commit timestamps, and your ticket transitions carry server timestamps in whatever timezone your project management system runs.

Aligning these three timelines requires explicit timezone normalization at ingestion time. Applying it at query time produces different results depending on the reader's local timezone, which makes aggregated team metrics non-reproducible.

Handling throughput limits

At engineering-org scale, querying usage across hundreds of developers and months of history involves enough API calls to hit rate limiting if your ingestion job is not designed for it.

Managing request volume

Building this yourself means owning the following work indefinitely. Read this section as scope for a build-versus-buy decision, because every item below is ongoing maintenance carried by whoever owns the pipeline.

• Respect the documented polling cadence. The Usage and Cost API supports polling once per minute for sustained use, and the Claude Enterprise Analytics API applies 60 requests per minute at the organization level rather than per key.
• Implement exponential backoff with jitter. When a request returns a 429 status, start with a one-second delay, then double on each subsequent failure. Add random jitter to prevent synchronized retry storms from concurrent workers.
• Batch to the right window per endpoint. Use 31-day windows on the Usage and Cost API. Expect one request per day on Claude Code analytics, where no wider window exists.
• Run backfill jobs during off-peak hours. If your analytics infrastructure shares rate limit headroom with developer-facing tooling, schedule bulk ingestion outside business hours.
• Checkpoint completed date ranges. If your ingestion job fails mid-run, resuming from scratch wastes quota. Write completed ranges to durable storage so a retry picks up where the failure occurred.

Estimating how long backfill takes

Backfill duration scales with organization size and usage history. Per-day requests on Claude Code analytics mean a year of history is 365 sequential calls, which the polling cadence above bounds rather than your own throughput.

Plan for hours rather than minutes on the first run, and treat completeness as the gate rather than elapsed time. Confirm that every user and project relevant to your analysis has ingested before you run the first AI impact report, because a partial load produces a regression across a partial team.

Resolving entities across your toolchain

Token counts and cost figures in isolation tell you nothing about whether your team shipped more value. Normalization connects that data to the commits, pull requests, and tickets that represent delivered work. The hardest problem in that layer is matching AI sessions to the commits, pull requests, and tickets they produced, which usually carry no identifier linking them together at all. Identity mismatches across systems compound the problem, but they are not the primary one.

Why identifiers diverge

The same person routinely appears under different identifiers in version control, project management, and Claude, which is common in organizations that did not standardize single sign-on (SSO) from the beginning. Until those resolve to one canonical contributor record, every team-level metric is wrong.

How minware resolves them

minware's patent-pending hypercube data model associates Claude Code agent sessions with the commits and pull requests they produced. Those then link through to tickets and epics, recovering relationships that carry no structured link between systems. Identity resolution supports that, reconciling mismatched names and emails across version control, project management, and AI tools into one canonical contributor record.

Incomplete ticket linking does affect traceability, which is why minware also surfaces best practice metrics flagging which branches lack ticket links.

Correlating token spend with delivery outcomes

This section produces the answer your board is asking for. Credential setup, ingestion, and normalization are infrastructure that exists to make it possible.

Running the regression

Linear regression is the primary methodology for connecting token spend to delivery outcomes. The regression fits a line through data points representing teams and time windows, where the x-axis is token spend and the y-axis is a value delivery metric such as story points completed.

The slope of that line is the ROI figure itself: the change in story points completed per additional dollar of token spend. The R-squared value reports how much of the variation in delivery the spend actually explains. An R-squared of 0.7 would mean roughly 70% of the variation in delivery outcomes across teams and time periods tracks with differences in token spend. Your own value is the one that matters, and a low one is itself a finding.

Correlation is not causation. Teams that spend most on AI are often already the strongest performers, and developers choose when to reach for an agent, so a positive slope needs a plausible causal story before it drives a budget decision. Name those confounders when you present the number, because your audience will raise them otherwise.

Do not use pull requests merged or lines of code as the y-axis. Those are throughput metrics measuring code output volume, and a team can merge more pull requests while shipping fewer completed roadmap items. The change failure rate guide for AI-generated code shows how throughput and quality diverge in AI-assisted workflows. That is why rework rate sits alongside your delivery regression as a guardrail rather than a substitute for it.

Breaking down usage by team

Breaking down token spend and story points completed by team reveals which teams show the strongest delivery correlation and which are spending at high rates with no corresponding delivery signal. That gives you a conversation to have with one team, instead of a single conclusion applied across the org.

minware's hypercube data model makes it possible to slice the same regression by team, project, or time period without writing custom queries. Match the dimension to the metric's data source: project for ticket-based metrics like story points completed, repository for code-based metrics like commits and PR cycle time.

Watching for review-stage bottlenecks

Story points completed staying flat while PR review time climbs in step with token spend is the pattern worth catching early. More code arriving for review lengthens the wait for a first human review, so the extra output sits in the queue and never reaches delivery.

Track both together. If delivery outcomes hold steady and review time is stable, the spend is being absorbed cleanly. The invisible wait time guide covers how to identify these accumulation patterns in distributed teams.

Attributing spend to roadmap items

For cost capitalization, the practice of recording qualifying engineering effort as a capital asset rather than an operating expense, and for investment decisions, connect token cost to specific epics by following the link chain from agent sessions to commits, commits to pull requests, pull requests to tickets, and tickets to epics.

That chain produces a dollar cost figure per roadmap initiative in the same data model that powers project completion tracking and burnup charts against due dates, giving finance the attribution view they need without a separate manual calculation.

Phasing the implementation

The four weeks below cover access and telemetry setup, historical backfill, identity normalization, and the first regression run in sequence.

Week 1: validating access and connecting telemetry

Generate your key in the console matching your organization type, store it in your secrets manager, and confirm connectivity by querying the usage report endpoint for a 7-day window. Validate that the response includes mappable email addresses. If you are using SCIM, confirm your identity provider mapping is exportable before Week 2. Set up your OpenTelemetry collector configuration to export Claude Code telemetry to your analytics infrastructure.

Week 2: configuring ingest and backfill

Initiate the historical backfill, using 31-day windows on the Usage and Cost API and per-day requests on Claude Code analytics. Run the job during off-peak hours with exponential backoff configured.

In parallel, verify that your OpenTelemetry collector is deployed and capturing session data. The sooner the collector is live, the more session-level history you accumulate, and the analytics endpoints cover the period before it.

Week 3: linking commits to delivery records

Connect your version control system, such as GitHub, GitLab, Bitbucket, or Azure DevOps, and your project management system, such as Jira, Linear, Azure Boards, or GitHub Issues, alongside the Claude Admin API. Run entity resolution across all three sources and review the mapping output. Feed your team hierarchy or HR export to enable team-level breakdowns. At this point your data model spans agent sessions, commits, pull requests, tickets, and epics in one normalized layer.

Week 4: reading your first results

Run your first regression of story points completed against token spend across teams and time windows. Read the slope and the R-squared value. Pull rework rate and PR review time as guardrail metrics on the same report.

Connecting the sources is the fast part. Getting the regression to answer your specific question means defining which tickets count as delivered and which contributors belong to which team, either in the report configuration yourself or with a customer success agent. That configuration effort is the real constraint, not the backfill timeline.

Prepare a one-page summary for your next executive review: the slope as the ROI figure, R-squared as the share of delivery variation the spend explains, the confounders behind that number, and the guardrail metrics showing where the trend is or is not moving.

Addressing common implementation hurdles

Four problems interrupt implementation progress more often than the rest, covering data availability, reporting granularity, identity, and the build-versus-buy question itself. A summary of the errors that cause them closes the section.

Accessing historical usage records

Historical Claude Code analytics data is retained and accessible through the API, with no specified deletion period, so the practical constraint is grain. Telemetry gives you per-prompt and per-session detail going forward with no backfill, while the analytics endpoints backfill at a per-user, per-day grain. Establish your baseline from the coarser source and let telemetry sharpen it over time.

Reporting when ticket data is messy

Messy ticket data does not prevent reporting. It changes what the reporting reveals. Best practice metrics surface where the process is breaking down, specifically the rate at which branches are linked to tickets, the rate at which tickets carry an estimate, and the rate at which active tickets are added to sprints.

Those findings are actionable. Each gap resolves to a specific list of unlinked pull requests or unestimated tickets a manager can work through, and the best practice consistency report shows those specific items rather than an aggregate score.

Resolving alias conflicts

Most aliases resolve automatically. The ones that do not tend to be personal accounts with no shared field to match on, or contributors who changed name or domain mid-history.

You can correct these through manual identity overrides in our account configuration, documented at minware.com/docs/account-configuration. Resolving aliases before the first regression matters, because a contributor split across two identities produces two low-spend data points instead of one high-spend point, which distorts the slope.

Deciding whether to build or buy

The honest comparison is not whether a custom pipeline can produce this data. It can. The question is whether it will keep producing accurate data as Anthropic updates its API schema, adds new models, or adjusts rate limit policies.

Dimension	Custom pipeline	minware normalized layer
Initial cost	Engineering effort for extract, transform, load (ETL) setup	Free trial, self-serve setup
Ongoing maintenance	Ongoing full-time equivalent (FTE) time, indefinitely	Included in subscription
API change handling	Manual update per breaking change	Handled by minware
Stakeholder questions	Falls on the pipeline builder	Customer success handles it
Entity resolution	Custom-built, identities and relationships alike	Automatic across identities and relationships, patent-pending

Avoiding the common pitfalls

Seven errors account for most failed or stalled implementations, and each maps back to a decision covered above.

• Standard Claude API misuse: treating the standard Claude API as a reporting surface. Usage reporting lives under the /v1/organizations/ namespace and needs an Admin API key.
• Credential confusion: using the wrong key type for your organization. Console and Enterprise keys carry different prefixes and different scope behavior.
• Wrong batching per endpoint: applying 31-day windows to Claude Code analytics, which accepts one day per request.
• Ignoring SCIM: skipping SCIM when SSO is already in place. It automates the user-to-team mapping you would otherwise build manually.
• Missing backoff: running backfill without exponential backoff. Rate limiting will interrupt the job and produce incomplete history.
• Count instead of cost: using token count rather than dollar cost as the regression variable. Count does not account for model price differences.
• Late timestamp normalization: skipping timezone normalization at ingestion, which produces non-reproducible metrics when queried from different timezones.

Turning usage data into a defensible answer

The Admin API gives you spend. Your version control and project management systems give you delivery. The slope between them is the figure a board can act on. Everything upstream of that regression exists to make the join trustworthy: the right key for your organization type, the right batching per endpoint, and an identity layer that resolves one developer to one contributor record across three systems.

Get that layer right and the ROI question stops requiring a manual rebuild every reporting cycle. Get it wrong and the regression returns a confident answer to the wrong question.

Getting started

Manual reporting from disconnected sources takes hours per cycle and produces data that is stale before it reaches the board. minware normalizes version control, project management, and AI tool data into one layer, so pre-built DORA and AI impact reports reflect live pipeline activity.

Start a 14-day free trial at minware.com, no credit card required, and connect your first data source to see how token spend correlates with your delivery outcomes.

FAQs

Does the Claude Admin API expose the raw text of developer prompts?

No. The usage, cost, and analytics endpoints return aggregated metadata rather than prompt text. The Compliance API content endpoints are a separate surface under their own scope and can read session transcripts, so scope your key accordingly. Whether prompt text reaches your analytics layer through telemetry is configured in your own OpenTelemetry setup, where it is redacted by default. That configuration stays under your control, and minware reports on whatever arrives.

How long does it take to see data after connecting the Claude Admin API?

Claude Code analytics data appears within about an hour of user activity, and usage and cost data within about five minutes. On the minware side, historical data ingestion on first connection can take hours, depending on repository size and data volume. minware then ingests new data via incremental loads, so delivery metrics reflect the most recent completed sync.

Can we track Claude usage if developers do not link their commits to tickets?

Yes. minware's patent-pending hypercube data model uses time-based linking to associate agent sessions with commits and tickets by modeling developer activity windows across connected systems. Explicit ticket links still make those associations more accurate, and best practice metrics give you a specific list of unlinked pull requests to close the gap over time.

Key terms glossary

Token spend: The estimated dollar cost of AI token consumption, and the primary continuous variable for correlating Claude Code usage with delivery outcomes. Token spend and token count are separate data points.

Story points completed: A value delivery metric totalling the story points field across completed tickets. It carries no sprint scoping of its own, which is what makes it usable as the y-axis in a regression across teams and time periods.

Linear regression: A statistical method measuring the relationship between token spend and a value delivery metric, where the slope of the fitted line represents the marginal change in delivery per dollar of token spend.

R-squared: The proportion of variance in a delivery metric that token spend explains. It reports how much of the variation the correlation accounts for, and it is not a confidence measure.

Entity resolution: Covers two problems of unequal difficulty. Identity resolution, matching a developer's identity across systems with different usernames or emails, is the easier half. Relationship recovery, linking commits, tickets, pull requests, and AI agent sessions that carry no structured link between systems, is the harder half and the subject of minware's pending patent.

Hypercube data model: minware's patent-pending data architecture linking entities across version control, project management, and AI tools by modeling developer activity windows over time, enabling analysis by any dimension without requiring explicit ticket links in every case.

Rework rate: A quality metric counting bugs created against pull requests merged. It is a broader measure of quality problems than change failure rate, and it sits alongside delivery outcomes as a guardrail confirming that higher token spend is not buying faster delivery at the cost of quality.

PR review time: The elapsed time from a pull request being opened to receiving a first review from another person. It is a distinct measurement from PR cycle time, which runs from a branch's first commit to merge.

Principle of Least Privilege (PoLP): Scoping API credentials to the minimum access required for the task. For usage tracking on a scoped key, that means read-only analytics access with no write permissions granted.

SCIM 2.0: System for Cross-domain Identity Management, an open standard for automating user provisioning between identity providers and applications. Used to maintain the mapping between directory identities and Claude accounts.