Datadog Anthropic Usage and Costs Integration
This skill connects the Anthropic usage and cost data feed. To trace LLM calls
made by an application, use dd-instrument-llmo instead.
Use scripts/setup.py relative to this file. It owns browser handoff, hidden
key entry in a separate terminal, the Anthropic key check, Pup OAuth
validation, duplicate prevention, one-shot registration, and secret redaction.
Do not reproduce its API reads or writes, except the read-only account
listing under Results and recovery.
The integration (anthropic-usage-and-costs) ingests token usage
(organization-wide on Platform, per user on Enterprise) as
anthropic.messages.* metrics and, when cost data ingestion is on,
Anthropic costs into Cloud Cost Management (CCM). Both are configured on one
Datadog account: the Anthropic key is its secret and ccm_enabled its setting,
so the script creates the account and turns on CCM in the same request.
Phase 0: Preflight
Datadog for Government is not supported. If pup auth status reports a
ddog-gov.com site, stop and tell the user to set up the integration from the
Datadog app instead. The script refuses Government sites too.
Pup. Installed and authenticated. The setup script performs every Datadog
request through pup api, which owns authentication selection, OAuth
refresh, site, and organization selection, and it validates Pup itself before
touching anything:
pup auth statusauthenticated: true→ continue.authenticated: false→ the setup script reportspup_not_authenticatedwith the exactpup auth logincommand. Ask before running it, and do not ask the user to create or export Datadog API or application keys.pupis missing (pup_cli_missing) → ask before installing it:brew tap datadog-labs/pack && brew install datadog-labs/pack/pup(macOS or Linux with Homebrew),curl -fsSL https://raw.githubusercontent.com/DataDog/pup/main/install.sh | sh, ornpm install -g @datadog/pup(Windows or anywhere with npm); see https://github.com/DataDog/pup. Then runpup auth login.
Pup version. The setup script uses Pup v2 CLI flags (such as
--no-envelope); Pup 1.x fails with an opaque pup_request_failed. Check:
pup --versionA major version of 2 or later is required. If it is older, ask before
upgrading. When the environment allows it, upgrade with the official
installer or npm as above. Some workspaces block piping a remote script to a
shell (curl | sh), and /usr/local/bin may not be user-writable; there,
install from the release archive in a fresh empty directory instead (replace
2.4.3 and the platform suffix with the latest release):
VERSION=2.4.3
curl -fsSLO "https://github.com/DataDog/pup/releases/download/v${VERSION}/pup_${VERSION}_Linux_x86_64.tar.gz" &&
curl -fsSLO "https://github.com/DataDog/pup/releases/download/v${VERSION}/pup_${VERSION}_checksums.txt" &&
grep "pup_${VERSION}_Linux_x86_64.tar.gz$" "pup_${VERSION}_checksums.txt" | sha256sum -c - &&
tar -xzf "pup_${VERSION}_Linux_x86_64.tar.gz" &&
sudo install -m 0755 ./pup /usr/local/bin/pup &&
pup auth loginPython. The flow runs scripts/setup.py, so confirm python3 is on
PATH before starting:
command -v python3 || echo "MISSING python3"Graphical terminal. The key prompt opens in a new desktop terminal window
(macOS Terminal, Windows Terminal or cmd.exe, or a Linux terminal with
DISPLAY or WAYLAND_DISPLAY set), or in a new tmux window when the agent
session runs inside tmux — which also works on headless hosts. If the user is
on SSH with no desktop session and no tmux, or in a container, stop and point
them to the Anthropic Usage and Costs tile in the Datadog app instead of
running the script.
The Anthropic key, decided by the plan:
- Platform plan → a key with Admin API access: an Admin key
(
sk-ant-admin...) or an organization-scoped key (sk-ant-usr...), created on the Claude Platform keys page (https://platform.claude.com/settings/keys). A workspace API key (sk-ant-api...) cannot read usage and cost data. This ingests organization-wide usage and cost by model, workspace, API key, and service tier. - Enterprise plan → an Analytics API key with the
read:analyticsscope, created athttps://claude.ai/admin-settings/api-access. Only the organization's Primary Owner can create one. This ingests per-user usage and cost by user, product (API, Claude Code, Claude.ai), model, and more.
Both: the key is shown only once, and cost data appears in Cloud Cost Management only if the Datadog org uses CCM.
Confirm the logged-in Datadog org
Before gathering anything else, ask whether to set up the integration for the
Datadog org the user is currently logged in to. Read the org's name from the
same pup session and site this run uses with pup api /api/v2/current_user
(the name of the orgs entry under included; the site is the one pup auth status reported). Then ask once with the host's native selector:
Do you want to set up this integration for the Datadog org <org name> on <site>?
- Yes → continue.
- No → stop. Have the user sign pup into the right org (see the pup step above), then ask again. Never continue on an org the user did not confirm.
Workflow
- [ ] Plan asked (platform | enterprise)
- [ ] Display name and cost choice collected
- [ ] Key explained, approval given
- [ ] setup.py run with --plan, DD_SITE/DD_ORG, ≥10 min timeout
- [ ] Status handled
- [ ] Verification started (Platform) or hourly-delay message given (Enterprise)Ask the plan with the host's native selector:
Is your Anthropic organization on the Platform plan (Claude API / Console) or the Enterprise plan (Claude for Enterprise)?
Pass the answer to every script command as
--plan platformor--plan enterprise. Never guess the plan.Gather the values not already supplied, in one interactive question form:
- Datadog integration display name: recommend a name that identifies the
Anthropic organization, such as
anthropic-production. - Cost data: whether to ingest Anthropic costs into Cloud Cost Management (on by default).
- Datadog integration display name: recommend a name that identifies the
Anthropic organization, such as
Explain the key the user will create, with the matching prerequisite in Phase 0: Preflight:
Platform: create a key with Admin API access on the Claude Platform keys page (the browser will open on it).
Enterprise: create an Analytics API key with the
read:analyticsscope athttps://claude.ai/admin-settings/api-access(the browser will open on it); it must be created by the organization's Primary Owner.Note: Anthropic's docs place Analytics API keys at
https://claude.ai/admin-settings/api-access, but this has not been confirmed against a live Enterprise org. If the user cannot find the option there, send them to the earlier location,https://claude.ai/analytics/api-keys; the key prompt in the terminal names both.
Either way they paste it into a separate terminal window that the script opens.
Get approval with the interactive question tool, once:
Title:
Approve Anthropic integration setupQuestion: ask this, with each step on its own line:
May I run the interactive setup? It will:
- Open the Anthropic key page for your plan.
- Ask you to paste the key into a hidden prompt in a new terminal.
- Check the key with Anthropic.
- Register the named Datadog integration account, with cost data ingestion <on|off>.
The key is never visible to the agent, and will not be printed, passed as a command argument, stored in a file, or returned in output.
Approve option:
Approve and open the secure key promptCancel option:
Cancel without making changes
Run setup:
python3 <SKILL_DIR>/scripts/setup.py --account-name "<DATADOG_INTEGRATION_NAME>" --plan <platform|enterprise>- On Windows, use
pythoninstead ofpython3. If the user declined cost data, append--disable-ccm. - Pup uses its default session, and picks the Datadog site from
DD_SITE(defaultdatadoghq.com): if the user's Pup session is on another site, run the command withDD_SITEset to it (e.g.datadoghq.eu); if they selected a named Pup organization session, also set theDD_ORGenvironment variable to that session's name. Set them the way the shell expects: aNAME=valueprefix on POSIX shells,$env:NAME="value";in PowerShell, orset "NAME=value" &&in cmd.exe. Use the same settings for every later script command. - Do not detach the process or redirect its input. The script opens
https://platform.claude.com/settings/keys?ws=default(Platform) orhttps://claude.ai/admin-settings/api-access(Enterprise), then waits for the user to create the key and paste it. Input is hidden like a password. Tell the user to switch to the new terminal when it appears — a tmux window namedanthropic-tokenwhen the session runs inside tmux. - Run the command with the longest command timeout your tool allows (at least 10 minutes). The user may take up to 5 minutes to enter the key, and Datadog requests have no client-side timeout. Killing the command during registration leaves the outcome unknown.
- The key goes only through the new terminal, which hands it back over a one-shot protected socket. Never ask the user to paste the key into chat, and never pass it through a command argument, environment variable, shell pipe, redirected input, or file.
- Setup checks Pup and lists existing accounts first, so a rerun with the
same name returns
already_configuredwithout asking for a key.
- On Windows, use
Handle the status under Results and recovery.
Verify under Getting the Most Out of Your Integration.
Results and recovery
Report the script's status and warnings without exposing credentials.
complete→ continue with Getting the Most Out of Your Integration, passing theanthropic_organization.idandusage_baselineit returned.already_configured→ the account exists. If the user wanted cost data andaccount.ccm_enabledisfalse, ask whether to turn it on; if yes, run:python3 <SKILL_DIR>/scripts/setup.py --account-name "<DATADOG_INTEGRATION_NAME>" --turn-on-ccmwith the same
DD_SITEandDD_ORGas setup. It needs no key: it updates onlyccm_enabledon that account and confirms the change (ccm_enabled, orccm_already_enabled).Repair (new key for an existing account) → setup does not replace the key on an existing account. Send the user to the Anthropic Usage and Costs tile in the Datadog app to replace it in the configuration panel.
pup_cli_outdated→ the installed Pup is older than v2 and cannot run this setup. Ask before upgrading it (see the Pup version preflight above), then rerun once the upgrade is done.invalid_anthropic_keyoranthropic_key_rejected→ a key Anthropic rejects never reaches Datadog, so nothing was written. Ask the user to create the right key for their plan (see Phase 0: Preflight) and rerun — and if it keeps happening, confirm the plan: a Platform key is rejected on the Enterprise check and vice versa.datadog_create_failedon the Enterprise plan with a message about an admin key → Datadog did not accept the Analytics key for this account. Report the message plainly; the user can set it up from the Anthropic Usage and Costs tile in the Datadog app instead.anthropic_check_failed→ Anthropic could not be reached to confirm the key; nothing was written. Rerun once the network allowsapi.anthropic.com.ambiguous_datadog_postordatadog_account_not_visible→ the account may exist but not be listed yet, so a rerun could create a duplicate. After a minute, list the accounts read-only withpup api v2/web-integrations/anthropic-usage-and-costs/accounts(sameDD_SITE/DD_ORG). If the name is listed, the account was created; a rerun with the same name confirms it asalready_configured. If not, do not rerun; send the user to the tile to check.duplicate_datadog_accounts→ report the account ids fromdetails.account_ids, and ask the user which to keep. Setup cannot choose.credential_entry_timeout→ nothing was written. Rerun when the user is ready to paste the key within 5 minutes.terminal_launch_failed,terminal_launch_unsupportedorterminal_helper_not_connected→ nothing was written. Ask the user to rerun from a desktop session, or to use the integration tile.Pup authentication failures → run
pup auth refresh; if that fails, runpup auth loginwith the reported missing scopes.Any other status → relay the script's message and reason code to the user, and rerun once the cause is fixed. If it says the write may have landed, check the account list first, as for
ambiguous_datadog_post.
Getting the Most Out of Your Integration
After the setup script returns complete, confirm that data is arriving and
then show the user what they can do with it, without blocking the conversation.
Enterprise plan: do not run the background check. Anthropic reports Enterprise usage in whole hours and Datadog only collects an hour once Anthropic has finalized it, so the first metrics typically appear 1–3 hours after setup — long after any 15-minute check would give up. Instead, tell the user, in these words:
"🎉 Your Anthropic integration is set up! Enterprise usage arrives in hourly batches, so your first metrics will show up in Datadog in about 1–3 hours. Look for
anthropic.*metrics — each point covers one hour of usage and is stamped at the end of that hour."
Embed setup's links.metrics (the Metrics Summary page filtered to
anthropic, on the user's own Datadog site) as the link on anthropic.*; if
setup returned no links, write anthropic.* without a link.
Then give two or three one-sentence next steps for once the data is in (for
example: chart usage by user_email and product; set a monitor on
anthropic.messages.output_tokens; and, when cost ingestion is on, that costs
will appear in Cloud Cost Management within about 24 hours), and stop.
Platform plan:
Start a background subagent with this task, using
pythoninstead ofpython3on Windows. The subagent runs in a fresh shell, so give it the sameDD_SITEandDD_ORGsettings setup used and include them in its command; otherwise it falls back to the default site and could check the wrong one:Run
python3 <SKILL_DIR>/scripts/verify_data.py --account-name "<DATADOG_INTEGRATION_NAME>" --anthropic-org-id "<ANTHROPIC_ORG_ID>" --baseline-since <usage_baseline.since> --baseline-total <usage_baseline.total>(drop both--baseline-*flags if setup'susage_baselinewasnull) with the sameDD_SITEandDD_ORGsetup used (omit any it did not set), passed through the execution tool's environment settings or set in the same shell invocation: POSIXDD_SITE=<site> DD_ORG=<session> python3 ...; PowerShell$env:DD_SITE="<site>"; $env:DD_ORG="<session>"; python ...; cmd.exeset "DD_SITE=<site>" && set "DD_ORG=<session>" && python .... Run it with a command timeout of at least 16 minutes. It polls Datadog for up to 15 minutes and prints JSON. Do not retry it or change anything. Report back itsstatus(succeeded,failed, orerror),checks,links,ccm_enabled,already_reporting_at_install,message, and anyerrorobject.Tell the user, in these words:
"Your Anthropic integration is set up! I'm now checking in the background that your usage metrics are arriving in Datadog. This can take up to 15 minutes, and I'll let you know as soon as they show up. Feel free to keep working in the meantime."
When the subagent reports, relay the result to the user.
succeeded: celebrate. Give a short, enthusiastic headline that starts with
🎉, such as "🎉 Your Anthropic usage metrics are now live in Datadog!", the links.metrics link
(anthropic.messages.input_tokens for this Anthropic organization in the
Metrics Explorer; usage points are stamped with when the usage happened, so tell
the user to widen the time range to the last few hours if the graph looks
empty), and two or three one-sentence next steps, for example: chart
token usage by model and workspace_name; set a monitor on
anthropic.messages.output_tokens to catch usage spikes; and, when
ccm_enabled is true, that Anthropic costs will appear in Cloud Cost
Management (links.costs) within about 24 hours (cost data is not part of the
check). If
already_reporting_at_install is true, add one sentence that this Anthropic
organization already had usage data in Datadog before setup (an earlier setup or
another account), so the new data could also come from there. Only describe what
the script confirmed.
failed: stay encouraging and relay the script's message. No new usage
data arrived during the wait: Platform usage reaches Datadog with a delay (often
~30 minutes) and only API usage produces data. If
already_reporting_at_install is true, mention that data for this
organization was already in Datadog before setup and did not count. Suggest
checking anthropic.messages.* metrics later before treating it as broken.
error: report the reason. For datadog_read_not_permitted, ask before
running the reported pup auth login --extra-scopes ... command.
If no subagent tool is available, run the same command yourself and report the result the same way.