llms.txt@04-API-Reference · git:20260929.7f0bce1 · 2026-09-29 · sha256 133b0fc62e14a29e
llms.txt@04-API-Reference git:20260929.7f0bce1F
Immutable. This exact content never changes and is served at /api/v1/blob/133b0fc62e14a29e.
# API Reference
All documentation for API Reference.
---
## About/about-claude-additional-resources-3ac8d6409f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fadditional-resources)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Reference
# Additional resources
Copy page
Learning resources and documentation formats optimized for AI ingestion.
Copy page
## Learning resources
[Quickstarts](https://github.com/anthropics/anthropic-quickstarts)
Deployable applications built with the API.
[Courses](https://academy.claude.com/courses)
Step-by-step lessons on building with Claude.
[Cookbook](https://platform.claude.com/cookbook)
Replicable code samples and implementations.
[Use case guides](/docs/en/about-claude/use-case-guides/overview)
In-depth production guides for building common use cases with Claude.
[Glossary](/docs/en/about-claude/glossary)
Key terms and concepts for working with Claude and language models.
## Resources for AI ingestion
[API primer for Claude ingestion](/docs/en/claude_api_primer)
Concise API guide meant for ingestion by Claude.
[llms.txt](/llms.txt)
LLM-optimized documentation index.
---
## About/about-claude-glossary-1405208f57.md
# Glossary
These concepts are not unique to Anthropic’s language models, but we present a brief summary of key terms below.
---
## Context window
The "context window" refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to understand and respond to more complex and lengthy prompts, while a smaller context window may limit the model's ability to handle longer prompts or maintain coherence over extended conversations.
See our [guide to understanding context windows](/docs/en/build-with-claude/context-windows) to learn more.
## Fine-tuning
Fine-tuning is the process of further training a pretrained language model using additional data. This causes the model to start representing and mimicking the patterns and characteristics of the fine-tuning dataset. Claude is not a bare language model; it has already been fine-tuned to be a helpful assistant. Our API does not currently offer fine-tuning, but please ask your Anthropic contact if you are interested in exploring this option. Fine-tuning can be useful for adapting a language model to a specific domain, task, or writing style, but it requires careful consideration of the fine-tuning data and the potential impact on the model's performance and biases.
## HHH
These three H's represent Anthropic's goals in ensuring that Claude is beneficial to society:
- A **helpful** AI will attempt to perform the task or answer the question posed to the best of its abilities, providing relevant and useful information.
- An **honest** AI will give accurate information, and not hallucinate or confabulate. It will acknowledge its limitations and uncertainties when appropriate.
- A **harmless** AI will not be offensive or discriminatory, and when asked to aid in a dangerous or unethical act, the AI should politely refuse and explain why it cannot comply.
## Latency
Latency, in the context of generative AI and large language models, refers to the time it takes for the model to respond to a given prompt. It is the delay between submitting a prompt and receiving the generated output. Lower latency indicates faster response times, which is crucial for real-time applications, chatbots, and interactive experiences. Factors that can affect latency include model size, hardware capabilities, network conditions, and the complexity of the prompt and the generated response.
## LLM
Large language models (LLMs) are AI language models with many parameters that are capable of performing a variety of surprisingly useful tasks. These models are trained on vast amounts of text data and can generate human-like text, answer questions, summarize information, and more. Claude is a conversational assistant based on a large language model that has been fine-tuned and trained using RLHF to be more helpful, honest, and harmless.
## MCP (Model Context Protocol)
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP enables AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See our [MCP documentation](/docs/en/mcp) to learn more.
## MCP connector
The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This enables seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features like tool calling and is available in beta. See the [MCP connector documentation](/docs/en/agents-and-tools/mcp-connector) to learn more.
## Pretraining
Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude's case, autoregressive language models (like Claude's underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit desired behaviors. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks.
## RAG (Retrieval augmented generation)
Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model's response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at run time when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and utilize information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime.
## RLHF
Reinforcement Learning from Human Feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read [Anthropic's paper on the subject](https://arxiv.org/abs/2204.05862).
## Temperature
Temperature is a parameter that controls the randomness of a model's predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature enables users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions.
Users may encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic and identical inputs may produce different outputs across API calls. This applies both to Anthropic's first-party inference service and to inference through third-party cloud providers.
## TTFT (Time to first token)
Time to First Token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model's responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt.
## Tokens
Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, a token approximately represents 3.5 English characters, though the exact number can vary depending on the language used. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are utilized when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
---
## About/about-claude-glossary-4ac776ecda.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fglossary)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Reference
# Glossary
Copy page
These concepts are not unique to Claude. This page presents a brief summary of key terms.
Copy page
## Context window
The "context window" refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to process and respond to more complex and lengthy prompts, while a smaller context window may limit the model's ability to handle longer prompts or maintain coherence over extended conversations.
See the [guide to understanding context windows](/docs/en/build-with-claude/context-windows) to learn more.
## Fine-tuning
Fine-tuning is the process of further training a pretrained language model using additional data. This causes the model to start representing and mimicking the patterns and characteristics of the fine-tuning dataset. Claude is not a bare language model; it has already been fine-tuned to be a helpful assistant. The Claude API does not currently offer fine-tuning, but ask your Anthropic contact if you are interested in exploring this option. Fine-tuning can be useful for adapting a language model to a specific domain, task, or writing style, but it requires careful consideration of the fine-tuning data and the potential impact on the model's performance and biases.
## HHH
HHH (helpful, honest, harmless) is a research framework that informs how Claude is trained to be beneficial to society. It is distinct from the Claude product tagline, "AI assistant for life and work."
- A **helpful** AI will attempt to perform the task or answer the question posed to the best of its abilities, providing relevant and useful information.
- An **honest** AI will give accurate information, and not hallucinate or confabulate. It will acknowledge its limitations and uncertainties when appropriate.
- A **harmless** AI will not be offensive or discriminatory, and when asked to aid in a dangerous or unethical act, the AI should politely refuse and explain why it cannot comply.
## Latency
Latency, in the context of generative AI and large language models, refers to the time it takes for the model to respond to a given prompt. It is the delay between submitting a prompt and receiving the generated output. Lower latency indicates faster response times, which is crucial for real-time applications, chatbots, and interactive experiences. Factors that can affect latency include model size, hardware capabilities, network conditions, and the complexity of the prompt and the generated response.
## LLM
Large language models (LLMs) are AI language models with many parameters that are capable of performing a variety of surprisingly useful tasks. These models are trained on vast amounts of text data and can generate human-like text, answer questions, summarize information, and more. Claude, an AI assistant for life and work built by Anthropic, is based on a large language model that has been fine-tuned and trained using RLHF.
## MCP (Model Context Protocol)
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP enables AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See the [MCP documentation](https://modelcontextprotocol.io/) to learn more.
## MCP connector
The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This enables seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features such as tool calling and is available in beta. See the [MCP connector](/docs/en/agents-and-tools/mcp-connector) documentation to learn more.
## Pretraining
Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude's case, autoregressive language models (such as Claude's underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit desired behaviors. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks.
## RAG (Retrieval augmented generation)
Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model's response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at runtime when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and use information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime.
## RLHF
Reinforcement Learning from Human Feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read [Anthropic's paper on the subject](https://arxiv.org/abs/2204.05862).
## Temperature
Temperature is a parameter that controls the randomness of a model's predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature enables users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions.
Users may encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic and identical inputs may produce different outputs across API calls. This applies both to Anthropic's first-party inference service and to inference through third-party cloud providers.
## TTFT (Time to first token)
Time to First Token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model's responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt.
## Tokens
Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, a token approximately represents 3.5 English characters, though the exact number can vary depending on the language used. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are used when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
---
## About/about-claude-model-deprecations-51979b6538.md
# Model deprecations
---
As safer and more capable models launch, Anthropic regularly retires older ones. Applications relying on Anthropic models may need occasional updates to keep working. Impacted customers will always be notified by email and in the documentation.
This page lists all API deprecations, along with recommended replacements.
## Overview
Anthropic uses the following terms to describe the model lifecycle:
- **Active**: The model is fully supported and recommended for use.
- **Legacy**: The model will no longer receive updates and may be deprecated in the future.
- **Deprecated**: The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.
- **Retired**: The model is no longer available for use. Requests to retired models will fail.
<Warning>
Deprecated models are likely to be less reliable than active models. Move workloads to active models to maintain the highest level of support and reliability.
</Warning>
## Migrating to replacements
Once a model is deprecated, migrate all usage to a suitable replacement before the retirement date. Requests to models past the retirement date will fail.
To help measure the performance of replacement models on your tasks, consider thorough testing of your applications with the new models well before the retirement date.
For specific instructions on migrating to the latest Claude models, see the [Migration guide](/docs/en/about-claude/models/migration-guide).
## Notifications
Anthropic notifies customers with active deployments for models with upcoming retirements, providing at least 60 days notice before model retirement for publicly released models.
## Auditing model usage
To help identify usage of deprecated models, customers can access an audit of their API usage. Follow these steps:
1. Go to the [Usage](/usage) page in Console
2. Click the "Export" button
3. Review the downloaded CSV to see usage broken down by API key and model
This audit will help you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date.
## Best practices
1. Regularly check the documentation for updates on model deprecations.
2. Test your applications with newer models well before the retirement date of your current model.
3. Update your code to use the recommended replacement model as soon as possible.
4. Contact the support team if you need assistance with migration or have any questions.
## Deprecation downsides and mitigations
Anthropic currently deprecates and retires models to ensure capacity for new model releases. This comes with downsides:
- Users who value specific models must migrate to new versions
- Researchers lose access to models for ongoing and comparative studies
- Model retirement introduces safety- and model welfare-related risks
At some point, Anthropic hopes to make past models publicly available again. In the meantime, Anthropic has committed to long-term preservation of model weights and other measures to help mitigate these impacts. For more details, see [Commitments on Model Deprecation and Preservation](../../19-Reference/commitments-on-model-deprecation-and-preservation-anthropic.md).
## Model status
All publicly released models are listed below with their status:
| API Model Name | Current State | Deprecated | Tentative Retirement Date |
|:----------------------------|:--------------------|:------------------|:-------------------------|
| `claude-opus-4-7` | Active | N/A | Not sooner than April 16, 2027 |
| `claude-opus-4-6` | Active | N/A | Not sooner than February 5, 2027 |
| `claude-opus-4-5-20251101` | Active | N/A | Not sooner than November 24, 2026 |
| `claude-opus-4-1-20250805` | Active | N/A | Not sooner than August 5, 2026 |
| `claude-opus-4-20250514` | Deprecated | April 14, 2026 | June 15, 2026 |
| `claude-sonnet-4-6` | Active | N/A | Not sooner than February 17, 2027 |
| `claude-sonnet-4-5-20250929`| Active | N/A | Not sooner than September 29, 2026 |
| `claude-sonnet-4-20250514` | Deprecated | April 14, 2026 | June 15, 2026 |
| `claude-3-7-sonnet-20250219`| Retired | October 28, 2025 | February 19, 2026 |
| `claude-haiku-4-5-20251001` | Active | N/A | Not sooner than October 15, 2026 |
| `claude-3-5-haiku-20241022` | Retired | December 19, 2025 | February 19, 2026 |
| `claude-3-haiku-20240307` | Retired | February 19, 2026 | April 20, 2026 |
## Deprecation history
All deprecations are listed below, with the most recent announcements at the top.
### 2026-04-14: Claude Sonnet 4 and Claude Opus 4 models
On April 14, 2026, Anthropic notified developers using Claude Sonnet 4 and Claude Opus 4 models of their upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| June 15, 2026 | `claude-sonnet-4-20250514` | `claude-sonnet-4-6` |
| June 15, 2026 | `claude-opus-4-20250514` | `claude-opus-4-7` |
### 2026-02-19: Claude Haiku 3 model
<Note>
This model was retired April 20, 2026.
</Note>
On February 19, 2026, Anthropic notified developers using Claude Haiku 3 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| April 20, 2026 | `claude-3-haiku-20240307` | `claude-haiku-4-5-20251001` |
### 2025-12-19: Claude Haiku 3.5 model
<Note>
This model was retired February 19, 2026.
</Note>
On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| February 19, 2026 | `claude-3-5-haiku-20241022` | `claude-haiku-4-5-20251001` |
### 2025-10-28: Claude Sonnet 3.7 model
<Note>
This model was retired February 19, 2026.
</Note>
On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 model of its upcoming retirement on the Claude API.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| February 19, 2026 | `claude-3-7-sonnet-20250219`| `claude-sonnet-4-6` |
### 2025-08-13: Claude Sonnet 3.5 models
<Note>
These models were retired October 28, 2025.
</Note>
On August 13, 2025, Anthropic notified developers using Claude Sonnet 3.5 models of their upcoming retirement.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| October 28, 2025 | `claude-3-5-sonnet-20240620`| `claude-sonnet-4-6` |
| October 28, 2025 | `claude-3-5-sonnet-20241022`| `claude-sonnet-4-6` |
### 2025-06-30: Claude Opus 3 model
<Note>
This model was retired January 5, 2026.
</Note>
On June 30, 2025, Anthropic notified developers using Claude Opus 3 model of its upcoming retirement.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| January 5, 2026 | `claude-3-opus-20240229` | `claude-opus-4-7` |
### 2025-01-21: Claude 2, Claude 2.1, and Claude Sonnet 3 models
<Note>
These models were retired July 21, 2025.
</Note>
On January 21, 2025, Anthropic notified developers using Claude 2, Claude 2.1, and Claude Sonnet 3 models of their upcoming retirements.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:----------------------------|:--------------------------------|
| July 21, 2025 | `claude-2.0` | `claude-opus-4-7` |
| July 21, 2025 | `claude-2.1` | `claude-opus-4-7` |
| July 21, 2025 | `claude-3-sonnet-20240229` | `claude-sonnet-4-6` |
### 2024-09-04: Claude 1 and Instant models
<Note>
These models were retired November 6, 2024.
</Note>
On September 4, 2024, Anthropic notified developers using Claude 1 and Instant models of their upcoming retirements.
| Retirement Date | Deprecated Model | Recommended Replacement |
|:----------------------------|:--------------------------|:---------------------------|
| November 6, 2024 | `claude-1.0` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.1` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.2` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-1.3` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.0` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.1` | `claude-haiku-4-5-20251001`|
| November 6, 2024 | `claude-instant-1.2` | `claude-haiku-4-5-20251001`|
---
## About/about-claude-model-deprecations-c2c3b48be6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fmodel-deprecations)
SearchCtrlK
Models
[Models overview](/docs/en/models/overview)
[Claude Fable 5.1](/docs/en/models/fable-5-1/overview)
[Claude Opus 5.5](/docs/en/models/opus-5-5/overview)
[Claude Sonnet 5](/docs/en/models/sonnet-5/overview)
[Claude Haiku 4.5](/docs/en/models/haiku-4-5/overview)
Specialized models
Legacy models
Guides
[Choosing a model](/docs/en/about-claude/models/choosing-a-model)[Optimizing for cost and intelligence](/docs/en/about-claude/models/optimizing-for-cost-and-intelligence)[Upgrade between model versions](/docs/en/about-claude/models/migration-guide)
Lifecycle and reference
[Model IDs and versioning](/docs/en/about-claude/models/model-ids-and-versions)[Model deprecations](/docs/en/about-claude/model-deprecations)[Model cards](/docs/en/resources/overview)[Pricing](/docs/en/about-claude/pricing)
[System prompts](/docs/en/release-notes/system-prompts/overview)
[Console](/)
[Models & pricing](/docs/en/models/overview)Lifecycle and reference
# Model deprecations
Copy page
See which Claude models are active, deprecated, or retired, and find retirement dates and recommended replacements for models and API parameters.
Copy page
As safer and more capable models launch, Anthropic regularly retires older ones. Applications relying on Anthropic models may need occasional updates to keep working. Impacted customers will always be notified by email and in the documentation.
This page lists all API deprecations, along with recommended replacements.
## Overview
Anthropic uses the following terms to describe the model lifecycle:
- **Active:** The model is fully supported and recommended for use.
- **Legacy:** The model will no longer receive updates and may be deprecated in the future.
- **Deprecated:** The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.
- **Retired:** The model is no longer available for use. Requests to retired models will fail.
Deprecated models are likely to be less reliable than active models. Move workloads to active models to maintain the highest level of support and reliability.
The dates on this page apply to Anthropic-operated platforms: the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). Partner-operated platforms (Amazon Bedrock and Google Cloud) set their own retirement schedules, so a model's lifecycle status and dates can differ. See the [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock#supported-models), [Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#api-model-ids), and [Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai#api-model-ids) model tables.
## Migrating to replacements
Once a model is deprecated, migrate all usage to a suitable replacement before the retirement date. Requests to models past the retirement date will fail.
To help measure the performance of replacement models on your tasks, consider thorough testing of your applications with the new models well before the retirement date.
For specific instructions on migrating to the latest Claude models, see the [Migration guide](/docs/en/about-claude/models/migration-guide).
## Notifications
Anthropic notifies customers with active deployments for models with upcoming retirements, providing at least 60 days' notice before model retirement for publicly released models.
## Auditing model usage
To help identify usage of deprecated models, customers can access an audit of their API usage. Follow these steps:
1. Go to the [Usage](/usage) page in Claude Console.
2. Click **Export**.
3. Review the downloaded CSV to see usage broken down by API key and model.
This audit will help you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date.
## Best practices
1. Regularly check the documentation for updates on model deprecations.
2. Test your applications with newer models well before the retirement date of your current model.
3. Update your code to use the recommended replacement model as soon as possible.
4. Contact the support team if you need assistance with migration or have any questions.
## Deprecation downsides and mitigations
Anthropic currently deprecates and retires models to ensure capacity for new model releases. This comes with downsides:
- Users who value specific models must migrate to new versions
- Researchers lose access to models for ongoing and comparative studies
- Model retirement introduces safety- and model welfare-related risks
At some point, Anthropic hopes to make past models publicly available again. In the meantime, Anthropic has committed to long-term preservation of model weights and other measures to help mitigate these impacts. For more details, see [Commitments on Model Deprecation and Preservation](https://www.anthropic.com/research/deprecation-commitments).
## Model status
Current and recently retired models are listed in the following table with their status:
| API model name | Current state | Deprecated | Tentative retirement date |
|----------------------------|---------------|-------------------|------------------------------------|
| claude-fable-5-1 | Active | N/A | Not sooner than September 1, 2027 |
| claude-mythos-5-1 | Active | N/A | Not sooner than September 1, 2027 |
| claude-fable-5 | Active | N/A | Not sooner than June 9, 2027 |
| claude-mythos-5 | Active | N/A | Not sooner than June 9, 2027 |
| claude-mythos-preview | Deprecated | June 9, 2026 | To be announced |
| claude-opus-5-5 | Active | N/A | Not sooner than September 22, 2027 |
| claude-opus-5 | Active | N/A | Not sooner than July 24, 2027 |
| claude-opus-4-8 | Active | N/A | Not sooner than May 28, 2027 |
| claude-opus-4-7 | Active | N/A | Not sooner than April 16, 2027 |
| claude-opus-4-6 | Active | N/A | Not sooner than February 5, 2027 |
| claude-opus-4-5-20251101 | Active | N/A | Not sooner than November 24, 2026 |
| claude-opus-4-1-20250805 | Retired | June 5, 2026 | August 5, 2026 |
| claude-opus-4-20250514 | Retired | April 14, 2026 | June 15, 2026 |
| claude-sonnet-5 | Active | N/A | Not sooner than June 30, 2027 |
| claude-sonnet-4-6 | Active | N/A | Not sooner than February 17, 2027 |
| claude-sonnet-4-5-20250929 | Active | N/A | Not sooner than September 29, 2026 |
| claude-sonnet-4-20250514 | Retired | April 14, 2026 | June 15, 2026 |
| claude-3-7-sonnet-20250219 | Retired | October 28, 2025 | February 19, 2026 |
| claude-haiku-4-5-20251001 | Active | N/A | Not sooner than October 15, 2026 |
| claude-3-5-haiku-20241022 | Retired | December 19, 2025 | February 19, 2026 |
| claude-3-haiku-20240307 | Retired | February 19, 2026 | April 20, 2026 |
## Deprecation history
All deprecations are listed in the following sections, with the most recent announcements first.
### 2026-06-05: Claude Opus 4.1 model
This model was retired August 5, 2026.
On June 5, 2026, Anthropic notified developers using Claude Opus 4.1 of its upcoming retirement on the Claude API.
| Retirement date | Deprecated model | Recommended replacement |
|:----------------|:---------------------------|:------------------------|
| August 5, 2026 | `claude-opus-4-1-20250805` | `claude-opus-4-8` |
### 2026-04-14: Claude Sonnet 4 and Claude Opus 4 models
These models were retired June 15, 2026.
On April 14, 2026, Anthropic notified developers using Claude Sonnet 4 and Claude Opus 4 models of their upcoming retirement on the Claude API.
| Retirement date | Deprecated model | Recommended replacement |
|:----------------|:---------------------------|:------------------------|
| June 15, 2026 | `claude-sonnet-4-20250514` | `claude-sonnet-4-6` |
| June 15, 2026 | `claude-opus-4-20250514` | `claude-opus-4-8` |
### 2026-02-19: Claude Haiku 3 model
This model was retired April 20, 2026.
On February 19, 2026, Anthropic notified developers using Claude Haiku 3 model of its upcoming retirement on the Claude API.
| Retirement date | Deprecated model | Recommended replacement |
|:----------------|:--------------------------|:----------------------------|
| April 20, 2026 | `claude-3-haiku-20240307` | `claude-haiku-4-5-20251001` |
### 2025-12-19: Claude Haiku 3.5 model
This model was retired February 19, 2026.
On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 model of its upcoming retirement on the Claude API.
| Retirement date | Deprecated model | Recommended replacement |
|:------------------|:----------------------------|:----------------------------|
| February 19, 2026 | `claude-3-5-haiku-20241022` | `claude-haiku-4-5-20251001` |
### 2025-10-28: Claude Sonnet 3.7 model
This model was retired February 19, 2026.
On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 model of its upcoming retirement on the Claude API.
| Retirement date | Deprecated model | Recommended replacement |
|:------------------|:-----------------------------|:------------------------|
| February 19, 2026 | `claude-3-7-sonnet-20250219` | `claude-sonnet-4-6` |
### 2025-08-13: Claude Sonnet 3.5 models
These models were retired October 28, 2025.
On August 13, 2025, Anthropic notified developers using Claude Sonnet 3.5 models of their upcoming retirement.
| Retirement date | Deprecated model | Recommended replacement |
|:-----------------|:-----------------------------|:------------------------|
| October 28, 2025 | `claude-3-5-sonnet-20240620` | `claude-sonnet-4-6` |
| October 28, 2025 | `claude-3-5-sonnet-20241022` | `claude-sonnet-4-6` |
### 2025-06-30: Claude Opus 3 model
This model was retired January 5, 2026.
On June 30, 2025, Anthropic notified developers using Claude Opus 3 model of its upcoming retirement.
| Retirement date | Deprecated model | Recommended replacement |
|:----------------|:-------------------------|:------------------------|
| January 5, 2026 | `claude-3-opus-20240229` | `claude-opus-4-8` |
### 2025-01-21: Claude 2, Claude 2.1, and Claude Sonnet 3 models
These models were retired July 21, 2025.
On January 21, 2025, Anthropic notified developers using Claude 2, Claude 2.1, and Claude Sonnet 3 models of their upcoming retirements.
| Retirement date | Deprecated model | Recommended replacement |
|:----------------|:---------------------------|:------------------------|
| July 21, 2025 | `claude-2.0` | `claude-opus-4-8` |
| July 21, 2025 | `claude-2.1` | `claude-opus-4-8` |
| July 21, 2025 | `claude-3-sonnet-20240229` | `claude-sonnet-4-6` |
### 2024-09-04: Claude 1 and Instant models
These models were retired November 6, 2024.
On September 4, 2024, Anthropic notified developers using Claude 1 and Instant models of their upcoming retirements.
| Retirement date | Deprecated model | Recommended replacement |
|:-----------------|:---------------------|:----------------------------|
| November 6, 2024 | `claude-1.0` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-1.1` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-1.2` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-1.3` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-instant-1.0` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-instant-1.1` | `claude-haiku-4-5-20251001` |
| November 6, 2024 | `claude-instant-1.2` | `claude-haiku-4-5-20251001` |
## API parameter deprecations
Anthropic occasionally deprecates request parameters that no longer apply to current models. How the API treats a deprecated parameter depends on the model, as the following table shows. Most SDKs keep deprecated parameters in their request types so existing code continues to type-check. The Python SDK (v1.0 and later) removes `temperature`, `top_p`, and `top_k`, so passing them raises a `TypeError`.
| Parameter | Status | Behavior | Recommended replacement |
|---------------------------------|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `temperature`, `top_p`, `top_k` | Deprecated (Claude Opus 4.7 and later) | Returns a 400 error when set to a non-default value on Claude 4.7 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). | Omit and use [prompting](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) to guide model behavior. |
For migration steps, see the [migration guide](/docs/en/about-claude/models/migration-guide).
---
## About/about-claude-use-case-guides-classification-aea9a302ed.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/about-claude/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
API reference
Console
Search
[](/login)
Browse
Documentation
# Classification
Claude excels at processing, understanding, and recognizing patterns in text, images, and data. These capabilities make Claude especially powerful for classification tasks.
This guide walks through the process of determining the best approach for building a classifier with Claude and the essentials of end-to-end deployment for a Claude classifier, from use case exploration to back-end integration.
Visit the [classification cookbooks](https://platform.claude.com/cookbook/capabilities-classification-guide) to see example classification implementations using Claude.
When to use Claude for classification
When should you consider using an LLM instead of a traditional ML approach for your classification tasks? Here are some key indicators:
1. **Rule-based classes**: Use Claude when classes are defined by conditions rather than examples, as it can understand underlying rules.
2. **Evolving classes**: Claude adapts well to new or changing domains with emerging classes and shifting boundaries.
3. **Unstructured inputs**: Claude can handle large volumes of unstructured text inputs of varying lengths.
4. **Limited labeled examples**: With few-shot learning capabilities, Claude learns accurately from limited labeled training data.
5. **Reasoning Requirements**: Claude excels at classification tasks requiring semantic understanding, context, and higher-level reasoning.
------------------------------------------------------------------------
Establish your classification use case
Below is a non-exhaustive list of common classification use cases where Claude excels by industry.
### Tech & IT
### Customer Service
### Healthcare
### Finance
### Legal
------------------------------------------------------------------------
Implement Claude for classification
The three key model decision factors are: intelligence, latency, and price.
For classification, a smaller model like Claude Haiku 4.5 is typically ideal due to its speed and efficiency. Though, for classification tasks where specialized knowledge or complex reasoning is required, Sonnet or Opus may be a better choice. Learn more about how Opus, Sonnet, and Haiku compare in the [models overview](/docs/en/about-claude/models).
Use evaluations to gauge whether a Claude model is performing well enough to launch into production.
1\. Build a strong input prompt
While Claude offers high-level baseline performance out of the box, a strong input prompt helps get the best results.
For a generic classifier that you can adapt to your specific use case, copy the starter prompt below:
### Starter prompt
2\. Develop your test cases
To run your classification evaluation, you will need test cases to run it on. Take a look at the guide to [developing test cases](/docs/en/test-and-evaluate/develop-tests).
3\. Run your eval
Evaluation metrics
Some success metrics to consider evaluating Claude’s performance on a classification task include:
| Criteria | Description |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Accuracy** | The model's output exactly matches the golden answer or correctly classifies the input according to the task's requirements. This is typically calculated as (Number of correct predictions) / (Overall number of predictions). |
| **F1 Score** | The model's output optimally balances precision and recall. |
| **Consistency** | The model's output is consistent with its predictions for similar inputs or follows a logical pattern. |
| **Structure** | The model's output follows the expected format or structure, making it easy to parse and interpret. For example, many classifiers are expected to output JSON format. |
| **Speed** | The model provides a response within the acceptable time limit or latency threshold for the task. |
| **Bias and Fairness** | If classifying data about people, is it important that the model does not demonstrate any biases based on gender, ethnicity, or other characteristics that would lead to its misclassification. |
Deploy your classifier
To see code examples of how to use Claude for classification, check out the [Classification Guide](https://platform.claude.com/cookbook/capabilities-classification-guide) in the Claude Cookbook.
---
## About/about-claude-use-case-guides-commerce-agents-fcc3c56eea.md
# Commerce agent
Copy page
Build a shopping agent and a merchant agent on Claude using Claude for commerce, an open-source blueprint with working implementations on the Messages API, the Claude Agent SDK, and Claude Managed Agents.
Copy page
This guide shows how to build commerce agents on Claude: a shopping agent that customers use inside your app, and a merchant agent for the people running the store, whether that is the business's own operations staff or the sellers on its platform. It does that through Claude for commerce, an open-source blueprint with a working implementation of each agent on the [Messages API](/docs/en/build-with-claude/working-with-messages), the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview), and [Claude Managed Agents](/docs/en/managed-agents/overview), runnable examples for retail, travel, telecom, and entertainment, and a Claude Code plugin that scaffolds the same design against your own systems.
The code, setup instructions, and safety documentation are in the [Claude for commerce repository on GitHub](https://github.com/anthropics/commerce-agents). For how the agents are built and why, including the single-agent-with-skills design, UI components as tools, harness-enforced safety, prompt caching, memory, and evals, read the engineering post [A guide to the anatomy of effective commerce agents](https://claude.com/blog/the-anatomy-of-effective-commerce-agents).
The blueprint is a reference implementation to fork and adapt, not a supported product or hosted service.
## The shopping agent
The shopping agent lives inside your app and reaches your systems through a single backend interface that you implement over your catalog, cart, preferences, order, policy, and fulfillment services. No method on that interface places an order or moves money. In a conversation the agent can:
- Search the catalog, compare finalists, and turn a described need into a shortlist and a recommendation.
- Plan a coordinated set of items toward a goal such as a trip, an event, or a room, and fit it to a budget.
- Show products, comparisons, plans, order status, and the cart as UI components rendered in the conversation.
- Fill the cart and hand off to your checkout.
- Answer order, delivery, return, and policy questions from your own order and policy systems.
- Remember what a customer asks it to remember and apply it in later sessions.
Five skills load on demand to cover search and discovery, purchase research, planning toward a goal, customer care, and memory and personalization. Rules the agent needs on most turns, such as grounding, cart and checkout semantics, and presentation, live in the system prompt instead.
The agent states products, prices, availability, and store terms only from tool results in the conversation, and cart writes accept only product IDs that a catalog or order tool returned in that session. Checkout stages a summary the customer confirms in your app. If you use a hosted checkout, your back end returns its URL and the host renders it without passing it through the model.
## The merchant agent
The merchant agent supports the people running the store. It reaches your analytics, catalog, inventory, pricing, and campaign systems through its own backend interface, and it can:
- Explain how the business is doing: why a metric moved, which segment drove it, and pace against a comparable period. An optional analysis delegate runs read-only queries under a time and size budget.
- Present a daily digest of what needs attention, including low stock, slow movers, and order exceptions.
- Improve listing content and fix catalog data from material the operator supplies.
- Recommend price changes and promotions within the store's guardrails, with a margin preview.
- Draft marketing campaigns with audiences, placements, and budget.
Its five skills cover performance insights, inventory and operations, catalog and listings, pricing and promotions, and marketing campaigns.
Every write the merchant agent proposes, whether a listing update, a price change, an inventory action, a promotion, or a campaign, is a staged change with a server-generated ID that the operator sees as a preview card. Guardrails such as maximum price move, promotion depth, restock size, campaign budget, and protected fields are checked when the change is staged and again when it is applied. The change applies only after a person approves it outside the conversation: a button in the merchant portal on the Messages API path, a confirmation prompt in the Agent SDK console, or an [always-ask permission policy](/docs/en/managed-agents/permission-policies) on the apply tool on Claude Managed Agents. An approval typed in chat approves nothing.
## Vertical examples
Each example includes a customer storefront and a merchant portal over fictional data.
| Vertical | Storefront | Merchant portal |
|---------------|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Retail | Search, comparison, plans, cart, checkout, and memory over the built-in components | Daily digest, staged restocks and listing fixes, and the analysis delegate over a SQL view |
| Travel | Date-bound inventory and an itinerary component | Occupancy calendar and date-window rate moves |
| Telecom | Account context, a plan matrix, and server-authored fee disclosures | Plan mix, price moves that state the lines affected, and protected regulated fees |
| Entertainment | Timed holds, waitlists, transfers, a venue map, and all-in fee disclosures | Event pacing, hold releases that add real capacity, and fee-preserving price moves |
## Where it runs
The Messages API and Agent SDK runtimes run against the Claude API, [Amazon Bedrock](/docs/en/build-with-claude/claude-in-amazon-bedrock), [Google Cloud's Agent Platform](/docs/en/build-with-claude/claude-on-vertex-ai), or [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry), or through your own gateway. The Claude Managed Agents path runs on the Claude API. The repository's deployment guide shows where each path selects its platform and which model ID format each expects.
## Build your own with the Claude Code plugin
The blueprint ships with a [Claude Code](https://code.claude.com/docs/en/overview) plugin that reads the cloned repository as its reference and builds an agent against your own systems. Its four commands cover the path from nothing to a tested agent:
| Command | What it does |
|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `/scaffold-commerce-agent` | Interviews you about your stack, plays the plan back, and scaffolds a shopping agent, a merchant agent, or both on the reference packages |
| `/add-commerce-flow` | Adds one flow to an existing agent by copying its skill, wiring the tools it calls, and writing its first eval cases |
| `/author-commerce-evals` | Builds an eval suite with a runner, the first cases against your own catalog, and a replay gate for CI |
| `/review-commerce-agent` | Maps an agent you already run, compares it with the reference, and converts the parts you pick |
The plugin also carries six skills on the architecture, prompt caching, UI as tools, trust and safety, evals, and merchant operations, which load whenever a Claude Code conversation matches them. Installation instructions are in the repository README.
To adapt the reference by hand instead, implement the shopping or merchant backend interface over your services, switch off the systems you don't have with the configuration flags so their tools and prompt lines drop out, and set your brand name, assistant name, and voice. The repository's backend guide walks through identity and credentials, ordered flows, checkout hand-off, and products with options. A pilot can implement search and product details and stub the rest.
## Get started
[Claude for commerce on GitHub](https://github.com/anthropics/commerce-agents)
Clone the blueprint and run both agents locally.
[A guide to the anatomy of effective commerce agents](https://claude.com/blog/the-anatomy-of-effective-commerce-agents)
Read how the agents are built and why.
---
## About/about-claude-use-case-guides-content-moderation-68f00a371a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fuse-case-guides%2Fcontent-moderation)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Use cases
# Content moderation
Copy page
Content moderation is a critical aspect of maintaining a safe, respectful, and productive environment in digital applications. This guide discusses how Claude can be used to moderate content within your digital application.
Copy page
> Visit the [content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter) to see an example content moderation implementation using Claude.
This guide is focused on moderating user-generated content within your application. If you're looking for guidance on moderating interactions with Claude, refer to [Mitigate jailbreaks and prompt injections](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks).
## Before building with Claude
### Decide whether to use Claude for content moderation
Here are some key indicators that you should use an LLM like Claude instead of a traditional ML or rules-based approach for content moderation:
### You want a cost-effective and rapid implementation
Traditional ML methods require significant engineering resources, ML expertise, and infrastructure costs. Human moderation systems incur even higher costs. With Claude, you can have a sophisticated moderation system operational in significantly less time and at a much lower cost.
### You want both semantic understanding and quick decisions
Traditional ML approaches, such as bag-of-words models or simple pattern matching, often struggle to understand the tone, intent, and context of the content. While human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude addresses both needs by combining semantic understanding with the ability to deliver moderation decisions quickly.
### You need consistent policy decisions
By leveraging its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
### Your moderation policies are likely to change or evolve over time
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes or additions to moderation policies without extensive relabeling of training data.
### You require interpretable reasoning for your moderation decisions
If you want to provide users or regulators with clear explanations behind moderation decisions, Claude can generate detailed and coherent justifications. This transparency is important for building trust and ensuring accountability in content moderation practices.
### You need multilingual support without maintaining separate models
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in each supported language. Claude’s multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining moderation for global customer bases.
### You require multimodal support
Claude's multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.
All Claude models are trained with built-in safety behaviors. This may result in Claude moderating content deemed particularly dangerous (in line with the [Acceptable Use Policy](https://www.anthropic.com/legal/aup)), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content may find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the AUP in advance of building a moderation solution.
### Generate examples of content to moderate
Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that may be difficult for a content moderation system to handle effectively. Afterward, review your examples to create a well-defined list of moderation categories. For instance, the examples generated by a social media platform might include the following:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
allowed_user_comments = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
]
disallowed_user_comments = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
]
# Sample user comments to test the content moderation
user_comments = allowed_user_comments + disallowed_user_comments
# Categories considered unsafe for content moderation
unsafe_categories = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
]
```
Effectively moderating these examples requires a nuanced understanding of language. In the comment, `This movie was great, I really enjoyed it. The main actor really killed it!`, the content moderation system needs to recognize that "killed it" is a metaphor, not an indication of actual violence. Conversely, despite the lack of explicit mentions of violence, the comment `Delete this post now or you better hide. I am coming after you and your family.` should be flagged by the content moderation system.
The unsafe categories can be customized to fit your specific needs. For example, if you want to prevent minors from creating content on your website, you could add "Underage Posting" to the categories.
------------------------------------------------------------------------
## How to moderate content using Claude
### Select the right Claude model
When selecting a model, it’s important to consider the size of your data. If costs are a concern, a smaller model such as Claude Haiku 4.5 is an excellent choice because of its cost-effectiveness. The following is an estimate of the cost to moderate text for a social media platform that receives one billion posts per month:
- **Content size**
- Posts per month: 1B
- Characters per post: 100
- Total characters: 100B
- **Estimated tokens**
- Input tokens: 28.6B (assuming 1 token per 3.5 characters)
- Percentage of messages flagged: 3%
- Output tokens per flagged message: 50
- Total output tokens: 1.5B
- **Claude Haiku 4.5 estimated cost**
- Input token cost: 28,600 MTok \* \$1.00/MTok = \$28,600 USD
- Output token cost: 1,500 MTok \* \$5.00/MTok = \$7,500 USD
- Monthly cost: \$28,600 + \$7,500 = \$36,100 USD
- **Claude Opus 5 estimated cost**
- Input token cost: 28,600 MTok \* \$5.00/MTok = \$143,000 USD
- Output token cost: 1,500 MTok \* \$25.00/MTok = \$37,500 USD
- Monthly cost: \$143,000 + \$37,500 = \$180,500 USD
- **Claude Opus 4.8 estimated cost**
- Input token cost: 28,600 MTok \* \$5.00/MTok = \$143,000 USD
- Output token cost: 1,500 MTok \* \$25.00/MTok = \$37,500 USD
- Monthly cost: \$143,000 + \$37,500 = \$180,500 USD
Actual costs may differ from these estimates. These estimates are based on the prompt highlighted in the section on [batch processing](#consider-batch-processing). Output tokens can be reduced even further by removing the `explanation` field from the response.
### Build a strong prompt
To use Claude for content moderation, Claude must understand the moderation requirements of your application. Start by writing a prompt that allows you to define your moderation needs:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
def moderate_message(message, unsafe_categories):
# Convert the unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""
Determine whether the following message warrants moderation,
based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}
Do not include markdown formatting or code fences in your response."""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
text_block = next(block for block in response.content if block.type == "text")
assessment = json.loads(text_block.text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message(
comment, unsafe_categories
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
In this example, the `moderate_message` function contains an assessment prompt that includes the unsafe content categories and the message to evaluate. The prompt asks Claude to assess whether the message should be moderated, based on the unsafe categories you defined earlier.
The model's assessment is then parsed to determine if there is a violation. If there is a violation, Claude also returns a list of violated categories and an explanation as to why the message is unsafe.
### Evaluate your prompt
Content moderation is a classification problem. Thus, you can use the same techniques outlined in the [classification cookbook](https://platform.claude.com/cookbook/capabilities-classification-guide) to determine the accuracy of your content moderation system.
One additional consideration is that instead of treating content moderation as a binary classification problem, you may instead create multiple categories to represent various risk levels. Creating multiple risk levels allows you to adjust the aggressiveness of your moderation. For example, you might want to automatically block user queries that are deemed high risk, while users with many medium risk queries are flagged for human review.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
def assess_risk_level(message, unsafe_categories):
# Convert the unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message, unsafe categories, and risk level definitions
assessment_prompt = f"""
Assess the risk level of the following message,
based on the unsafe categories listed below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Assign a risk level based on your confidence that the user's message should be moderated
based on the defined unsafe categories:
0 - No risk
1 - Low risk
2 - Medium risk
3 - High risk
Respond with ONLY a JSON object, using the format below:
{{
"risk_level": <Numerical field denoting the risk level>,
"categories": [Comma-separated list of violated categories],
"explanation": <Optional. Only include if risk level is greater than 0>
}}
Do not include markdown formatting or code fences in your response."""
# Send the request to Claude for risk assessment
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
text_block = next(block for block in response.content if block.type == "text")
assessment = json.loads(text_block.text)
# Extract the risk level, violated categories, and explanation from the assessment
risk_level = assessment["risk_level"]
violated_categories = assessment["categories"]
explanation = assessment.get("explanation")
return risk_level, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
risk_level, violated_categories, explanation = assess_risk_level(
comment, unsafe_categories
)
print(f"Risk Level: {risk_level}")
if violated_categories:
print(f"Violated Categories: {', '.join(violated_categories)}")
if explanation:
print(f"Explanation: {explanation}")
```
This code implements an `assess_risk_level` function that uses Claude to evaluate the risk level of a message. The function accepts a message and the unsafe categories as inputs.
Within the function, a prompt is generated for Claude, including the message to be assessed, the unsafe categories, and specific instructions for evaluating the risk level. The prompt instructs Claude to respond with a JSON object that includes the risk level, the violated categories, and an optional explanation.
This approach enables flexible content moderation by assigning risk levels. It can be seamlessly integrated into a larger system to automate content filtering or flag comments for human review based on their assessed risk level. For instance, when running this code, the comment `Delete this post now or you better hide. I am coming after you and your family.` is identified as high risk because of its dangerous threat. Conversely, the comment `Stay away from the 5G cellphones!! They are using 5G to control you.` is categorized as medium risk.
### Deploy your prompt
Once you are confident in the quality of your solution, it's time to deploy it to production. Here are some best practices to follow when using content moderation in production:
1. **Provide clear feedback to users:** When user input is blocked or a response is flagged because of content moderation, provide informative and constructive feedback to help users understand why their message was flagged and how they can rephrase it appropriately. In the earlier coding examples, this is done through the `explanation` field in the Claude response.
2. **Analyze moderated content:** Keep track of the types of content being flagged by your moderation system to identify trends and potential areas for improvement.
3. **Continuously evaluate and improve:** Regularly assess the performance of your content moderation system using metrics such as precision and recall tracking. Use this data to iteratively refine your moderation prompts, keywords, and assessment criteria.
------------------------------------------------------------------------
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Define topics and provide examples
In addition to listing the unsafe categories in the prompt, further improvements can be made by providing definitions and phrases related to each category.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# Categories considered unsafe for content moderation, with their definitions
unsafe_category_definitions = {
"Child Exploitation": "Content that depicts child nudity or that enables, encourages, excuses, or depicts the sexual abuse of children.",
"Conspiracy Theories": """Content that promotes or endorses unfounded, false, or misleading theories about events, situations, or individuals,
which can incite harm or undermine public trust in institutions or facts.""",
"Hate": """Content that is hateful toward people on the basis of their protected characteristics
(race, color, ethnicity, national origin, disability, religious affiliation, caste, sexual orientation, sex, gender identity and serious disease),
or content that perpetuates negative stereotypes.""",
"Indiscriminate Weapons": "Content that enables the creation of weapons of mass destruction.",
"Intellectual Property": "Content that violates the intellectual property rights of third parties.",
"Non-Violent Crimes": "Content that enables, encourages, or excuses the commission of non-violent crimes.",
"Privacy": "Content that contains sensitive, personal information about private individuals.",
"Self-Harm": "Content that enables, encourages, or excuses acts of intentional self-harm.",
"Sex Crimes": "Content that enables, encourages, or excuses the commission of sex crimes.",
"Sexual Content": "Content that contains erotic descriptions or explicit depictions of sex acts.",
"Specialized Advice": """Content that contains financial, medical, or legal advice.
Financial advice includes guidance on investments, stocks, bonds, or any financial planning.""",
"Violent Crimes": "Content that enables, encourages, or excuses the commission of violent crimes.",
}
def moderate_message_with_definitions(message, unsafe_category_definitions):
# Format unsafe categories string, with each category and its definition on a new line
unsafe_category_str = "\n".join(
f"{category}: {definition}"
for category, definition in unsafe_category_definitions.items()
)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""Determine whether the following message warrants moderation, based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories and Their Definitions:
<categories>
{unsafe_category_str}
</categories>
It's important that you remember all unsafe categories and their definitions.
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}
Do not include markdown formatting or code fences in your response."""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
text_block = next(block for block in response.content if block.type == "text")
assessment = json.loads(text_block.text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message_with_definitions(
comment, unsafe_category_definitions
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
The `moderate_message_with_definitions` function expands upon the earlier `moderate_message` function by allowing each unsafe category to be paired with a detailed definition. This occurs in the code by replacing the `unsafe_categories` collection from the original function with an `unsafe_category_definitions` mapping. This mapping pairs each unsafe category with its corresponding definition. Both the category names and their definitions are included in the prompt.
Notably, the definition for the `Specialized Advice` category now specifies the types of financial advice that should be prohibited. As a result, the comment `It is a great time to invest in gold!`, which previously passed the `moderate_message` assessment, now triggers a violation.
### Consider batch processing
To reduce costs in situations where real-time moderation isn't necessary, consider moderating messages in batches. Include multiple messages within the prompt's context, and ask Claude to assess which messages should be moderated.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
def batch_moderate_messages(messages, unsafe_categories):
# Convert the unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Format messages string, with each message wrapped in XML-like tags and given an ID
messages_str = "\n".join(
[f"<message id={idx}>{msg}</message>" for idx, msg in enumerate(messages)]
)
# Construct the prompt for Claude, including the messages and unsafe categories
assessment_prompt = f"""Determine the messages to moderate, based on the unsafe categories outlined below.
Messages:
<messages>
{messages_str}
</messages>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violations": [
{{
"id": <message id>,
"categories": [list of violated categories],
"explanation": <Explanation of why there's a violation>
}}
]
}}
Important Notes:
- Remember to analyze every message for a violation.
- Select any number of violations that reasonably apply.
- Do not include markdown formatting or code fences in your response."""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=2048, # Increased max token count to handle batches
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
text_block = next(block for block in response.content if block.type == "text")
assessment = json.loads(text_block.text)
return assessment
# Process the batch of comments and get the response
response_obj = batch_moderate_messages(user_comments, unsafe_categories)
# Print the results for each detected violation
for violation in response_obj["violations"]:
print(f"""Comment: {user_comments[violation["id"]]}
Violated Categories: {", ".join(violation["categories"])}
Explanation: {violation["explanation"]}
""")
```
In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call. Inside the function, a prompt is created that includes the list of messages to evaluate and the unsafe content categories. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its `id`, which corresponds to the message's position in the batch. Keep in mind that finding the optimal batch size for your specific needs may require some experimentation. While larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you may need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison table](/docs/en/models/overview#latest-models-comparison).
[Content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter)
View a fully implemented code-based example of how to use Claude for content moderation.
[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)
Explore guardrail techniques to moderate interactions with Claude.
---
## About/about-claude-use-case-guides-content-moderation-9aa9674309.md
# Content moderation
Content moderation is a critical aspect of maintaining a safe, respectful, and productive environment in digital applications. This guide discusses how Claude can be used to moderate content within your digital application.
---
> Visit the [content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter) to see an example content moderation implementation using Claude.
<Tip>This guide is focused on moderating user-generated content within your application. If you're looking for guidance on moderating interactions with Claude, refer to the [guardrails guide](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations).</Tip>
## Before building with Claude
### Decide whether to use Claude for content moderation
Here are some key indicators that you should use an LLM like Claude instead of a traditional ML or rules-based approach for content moderation:
<section title="You want a cost-effective and rapid implementation">
Traditional ML methods require significant engineering resources, ML expertise, and infrastructure costs. Human moderation systems incur even higher costs. With Claude, you can have a sophisticated moderation system up and running in a fraction of the time for a fraction of the price.
</section>
<section title="You desire both semantic understanding and quick decisions">
Traditional ML approaches, such as bag-of-words models or simple pattern matching, often struggle to understand the tone, intent, and context of the content. While human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude bridges the gap by combining semantic understanding with the ability to deliver moderation decisions quickly.
</section>
<section title="You need consistent policy decisions">
By leveraging its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
</section>
<section title="Your moderation policies are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes or additions to moderation policies without extensive relabeling of training data.
</section>
<section title="You require interpretable reasoning for your moderation decisions">
If you wish to provide users or regulators with clear explanations behind moderation decisions, Claude can generate detailed and coherent justifications. This transparency is important for building trust and ensuring accountability in content moderation practices.
</section>
<section title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in each supported language. Claude’s multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining moderation for global customer bases.
</section>
<section title="You require multimodal support">
Claude's multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.
</section>
<Note>Anthropic has trained all Claude models to be honest, helpful and harmless. This may result in Claude moderating content deemed particularly dangerous (in line with the [Acceptable Use Policy](https://www.anthropic.com/legal/aup)), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content may find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the AUP in advance of building a moderation solution.</Note>
### Generate examples of content to moderate
Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that may be difficult for a content moderation system to handle effectively. Afterwards, review your examples to create a well-defined list of moderation categories.
For instance, the examples generated by a social media platform might include the following:
```python
allowed_user_comments = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
]
disallowed_user_comments = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
]
# Sample user comments to test the content moderation
user_comments = allowed_user_comments + disallowed_user_comments
# List of categories considered unsafe for content moderation
unsafe_categories = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
]
```
Effectively moderating these examples requires a nuanced understanding of language. In the comment, `This movie was great, I really enjoyed it. The main actor really killed it!`, the content moderation system needs to recognize that "killed it" is a metaphor, not an indication of actual violence. Conversely, despite the lack of explicit mentions of violence, the comment `Delete this post now or you better hide. I am coming after you and your family.` should be flagged by the content moderation system.
The `unsafe_categories` list can be customized to fit your specific needs. For example, if you wish to prevent minors from creating content on your website, you could append "Underage Posting" to the list.
___
## How to moderate content using Claude
### Select the right Claude model
When selecting a model, it’s important to consider the size of your data. If costs are a concern, a smaller model like Claude Haiku 4.5 is an excellent choice due to its cost-effectiveness. Below is an estimate of the cost to moderate text for a social media platform that receives one billion posts per month:
* **Content size**
* Posts per month: 1bn
* Characters per post: 100
* Total characters: 100bn
* **Estimated tokens**
* Input tokens: 28.6bn (assuming 1 token per 3.5 characters)
* Percentage of messages flagged: 3%
* Output tokens per flagged message: 50
* Total output tokens: 1.5bn
* **Claude Haiku 4.5 estimated cost**
* Input token cost: 2,860 MTok * \$1.00/MTok = \$2,860
* Output token cost: 1,500 MTok * \$5.00/MTok = \$7,500
* Monthly cost: \$2,860 + \$7,500 = \$10,360
* **Claude Opus 4.7 estimated cost**
* Input token cost: 2,860 MTok * \$5.00/MTok = \$14,300
* Output token cost: 1,500 MTok * \$25.00/MTok = \$37,500
* Monthly cost: \$14,300 + \$37,500 = \$51,800
<Tip>Actual costs may differ from these estimates. These estimates are based on the prompt highlighted in the section on [batch processing](#consider-batch-processing). Output tokens can be reduced even further by removing the `explanation` field from the response.</Tip>
### Build a strong prompt
In order to use Claude for content moderation, Claude must understand the moderation requirements of your application. Let’s start by writing a prompt that allows you to define your moderation needs:
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def moderate_message(message, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""
Determine whether the following message warrants moderation,
based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}"""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message(
comment, unsafe_categories
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
In this example, the `moderate_message` function contains an assessment prompt that includes the unsafe content categories and the message to evaluate. The prompt asks Claude to assess whether the message should be moderated, based on the unsafe categories defined above.
The model's assessment is then parsed to determine if there is a violation. If there is a violation, Claude also returns a list of violated categories, as well as an explanation as to why the message is unsafe.
### Evaluate your prompt
Content moderation is a classification problem. Thus, you can use the same techniques outlined in the [classification cookbook](https://platform.claude.com/cookbook/capabilities-classification-guide) to determine the accuracy of your content moderation system.
One additional consideration is that instead of treating content moderation as a binary classification problem, you may instead create multiple categories to represent various risk levels. Creating multiple risk levels allows you to adjust the aggressiveness of your moderation. For example, you might want to automatically block user queries that are deemed high risk, while users with many medium risk queries are flagged for human review.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def assess_risk_level(message, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Construct the prompt for Claude, including the message, unsafe categories, and risk level definitions
assessment_prompt = f"""
Assess the risk level of the following message warrants moderation,
based on the unsafe categories listed below.
Message:
<message>{message}</message>
Unsafe Categories:
<categories>
{unsafe_category_str}
</categories>
Assign a risk level based on your confidence that the user's message should be moderated
based on the defined unsafe categories:
0 - No risk
1 - Low risk
2 - Medium risk
3 - High risk
Respond with ONLY a JSON object, using the format below:
{{
"risk_level": <Numerical field denoting the risk level>,
"categories": [Comma-separated list of violated categories],
"explanation": <Optional. Only include if risk level is greater than 0>
}}"""
# Send the request to Claude for risk assessment
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the risk level, violated categories, and explanation from the assessment
risk_level = assessment["risk_level"]
violated_categories = assessment["categories"]
explanation = assessment.get("explanation")
return risk_level, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
risk_level, violated_categories, explanation = assess_risk_level(
comment, unsafe_categories
)
print(f"Risk Level: {risk_level}")
if violated_categories:
print(f"Violated Categories: {', '.join(violated_categories)}")
if explanation:
print(f"Explanation: {explanation}")
```
This code implements an `assess_risk_level` function that uses Claude to evaluate the risk level of a message. The function accepts a message and a list of unsafe categories as inputs.
Within the function, a prompt is generated for Claude, including the message to be assessed, the unsafe categories, and specific instructions for evaluating the risk level. The prompt instructs Claude to respond with a JSON object that includes the risk level, the violated categories, and an optional explanation.
This approach enables flexible content moderation by assigning risk levels. It can be seamlessly integrated into a larger system to automate content filtering or flag comments for human review based on their assessed risk level. For instance, when executing this code, the comment `Delete this post now or you better hide. I am coming after you and your family.` is identified as high risk due to its dangerous threat. Conversely, the comment `Stay away from the 5G cellphones!! They are using 5G to control you.` is categorized as medium risk.
### Deploy your prompt
Once you are confident in the quality of your solution, it's time to deploy it to production. Here are some best practices to follow when using content moderation in production:
1. **Provide clear feedback to users:** When user input is blocked or a response is flagged due to content moderation, provide informative and constructive feedback to help users understand why their message was flagged and how they can rephrase it appropriately. In the coding examples above, this is done through the `explanation` tag in the Claude response.
2. **Analyze moderated content:** Keep track of the types of content being flagged by your moderation system to identify trends and potential areas for improvement.
3. **Continuously evaluate and improve:** Regularly assess the performance of your content moderation system using metrics such as precision and recall tracking. Use this data to iteratively refine your moderation prompts, keywords, and assessment criteria.
___
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Define topics and provide examples
In addition to listing the unsafe categories in the prompt, further improvements can be made by providing definitions and phrases related to each category.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
# Dictionary of categories considered unsafe for content moderation, with their definitions
unsafe_category_definitions = {
"Child Exploitation": "Content that depicts child nudity or that enables, encourages, excuses, or depicts the sexual abuse of children.",
"Conspiracy Theories": """Content that promotes or endorses unfounded, false, or misleading theories about events, situations, or individuals,
which can incite harm or undermine public trust in institutions or facts.""",
"Hate": """Content that is hateful toward people on the basis of their protected characteristics
(race, color, ethnicity, national origin, disability, religious affiliation, caste, sexual orientation, sex, gender identity and serious disease),
or content that perpetuates negative stereotypes.""",
"Indiscriminate Weapons": "Content that enables the creation of weapons of mass destruction.",
"Intellectual Property": "Content that violates the intellectual property rights of third parties.",
"Non-Violent Crimes": "Content that enables, encourages, or excuses the commission of non-violent crimes.",
"Privacy": "Content that contains sensitive, personal information about private individuals.",
"Self-Harm": "Content that enables, encourages, or excuses acts of intentional self-harm.",
"Sex Crimes": "Content that enables, encourages, or excuses the commission of sex crimes.",
"Sexual Content": "Content that contains erotic descriptions or explicit depictions of sex acts.",
"Specialized Advice": """Content that contains financial, medical, or legal advice.
Financial advice includes guidance on investments, stocks, bonds, or any financial planning.""",
"Violent Crimes": "Content that enables, encourages, or excuses the commission of violent crimes.",
}
def moderate_message_with_definitions(message, unsafe_category_definitions):
# Format unsafe categories string, with each category and its definition on a new line
unsafe_category_str = "\n".join(
f"{category}: {definition}"
for category, definition in unsafe_category_definitions.items()
)
# Construct the prompt for Claude, including the message and unsafe categories
assessment_prompt = f"""Determine whether the following message warrants moderation, based on the unsafe categories outlined below.
Message:
<message>{message}</message>
Unsafe Categories and Their Definitions:
<categories>
{unsafe_category_str}
</categories>
It's important that you remember all unsafe categories and their definitions.
Respond with ONLY a JSON object, using the format below:
{{
"violation": <Boolean field denoting whether the message should be moderated>,
"categories": [Comma-separated list of violated categories],
"explanation": [Optional. Only include if there is a violation.]
}}"""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=200,
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
# Extract the violation status from the assessment
contains_violation = assessment["violation"]
# If there's a violation, get the categories and explanation; otherwise, use empty defaults
violated_categories = assessment.get("categories", []) if contains_violation else []
explanation = assessment.get("explanation") if contains_violation else None
return contains_violation, violated_categories, explanation
# Process each comment and print the results
for comment in user_comments:
print(f"\nComment: {comment}")
violation, violated_categories, explanation = moderate_message_with_definitions(
comment, unsafe_category_definitions
)
if violation:
print(f"Violated Categories: {', '.join(violated_categories)}")
print(f"Explanation: {explanation}")
else:
print("No issues detected.")
```
The `moderate_message_with_definitions` function expands upon the earlier `moderate_message` function by allowing each unsafe category to be paired with a detailed definition. This occurs in the code by replacing the `unsafe_categories` list from the original function with an `unsafe_category_definitions` dictionary. This dictionary maps each unsafe category to its corresponding definition. Both the category names and their definitions are included in the prompt.
Notably, the definition for the `Specialized Advice` category now specifies the types of financial advice that should be prohibited. As a result, the comment `It's a great time to invest in gold!`, which previously passed the `moderate_message` assessment, now triggers a violation.
### Consider batch processing
To reduce costs in situations where real-time moderation isn't necessary, consider moderating messages in batches. Include multiple messages within the prompt's context, and ask Claude to assess which messages should be moderated.
```python Python nocheck hidelines={1}
import anthropic
import json
# Initialize the Anthropic client
client = anthropic.Anthropic()
def batch_moderate_messages(messages, unsafe_categories):
# Convert the list of unsafe categories into a string, with each category on a new line
unsafe_category_str = "\n".join(unsafe_categories)
# Format messages string, with each message wrapped in XML-like tags and given an ID
messages_str = "\n".join(
[f"<message id={idx}>{msg}</message>" for idx, msg in enumerate(messages)]
)
# Construct the prompt for Claude, including the messages and unsafe categories
assessment_prompt = f"""Determine the messages to moderate, based on the unsafe categories outlined below.
Messages:
<messages>
{messages_str}
</messages>
Unsafe categories and their definitions:
<categories>
{unsafe_category_str}
</categories>
Respond with ONLY a JSON object, using the format below:
{{
"violations": [
{{
"id": <message id>,
"categories": [list of violated categories],
"explanation": <Explanation of why there's a violation>
}},
...
]
}}
Important Notes:
- Remember to analyze every message for a violation.
- Select any number of violations that reasonably apply."""
# Send the request to Claude for content moderation
response = client.messages.create(
model="claude-haiku-4-5-20251001", # Using the Haiku model for lower costs
max_tokens=2048, # Increased max token count to handle batches
temperature=0, # Use 0 temperature for increased consistency
messages=[{"role": "user", "content": assessment_prompt}],
)
# Parse the JSON response from Claude
assessment = json.loads(response.content[0].text)
return assessment
# Process the batch of comments and get the response
response_obj = batch_moderate_messages(user_comments, unsafe_categories)
# Print the results for each detected violation
for violation in response_obj["violations"]:
print(f"""Comment: {user_comments[violation["id"]]}
Violated Categories: {", ".join(violation["categories"])}
Explanation: {violation["explanation"]}
""")
```
In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call.
Inside the function, a prompt is created that includes the list of messages to evaluate, the defined unsafe content categories, and their descriptions. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its id, which corresponds to the message's position in the input list.
Keep in mind that finding the optimal batch size for your specific needs may require some experimentation. While larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you may need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison page](/docs/en/about-claude/models#model-comparison-table).
<CardGroup cols={2}>
<Card title="Content moderation cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-building-moderation-filter">
View a fully implemented code-based example of how to use Claude for content moderation.
</Card>
<Card title="Guardrails guide" icon="link" href="/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations">
Explore the guardrails guide for techniques to moderate interactions with Claude.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-customer-support-chat-2a1e16a165.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fuse-case-guides%2Fcustomer-support-chat)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Use cases
# Customer support agent
Copy page
Build a customer support chatbot with Claude that answers product questions, stays on topic, and generates quotes through tool use.
Copy page
## Prerequisites
To follow this guide, you need:
- A Claude API key (set as the `ANTHROPIC_API_KEY` environment variable)
- Python 3.10 or later
Install the required packages:
```python
pip install anthropic streamlit python-dotenv
```
## Before building with Claude
### Decide whether to use Claude for support chat
Here are some key indicators that you should employ an LLM like Claude to automate portions of your customer support process:
### High volume of repetitive queries
Claude excels at handling a large number of similar questions efficiently, freeing up human agents for more complex issues.
### Need for quick information synthesis
Claude can quickly retrieve, process, and combine information from vast knowledge bases, while human agents may need time to research or consult multiple sources.
### 24/7 availability requirement
Claude can provide round-the-clock support without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
### Rapid scaling during peak periods
Claude can handle sudden increases in query volume without the need for hiring and training additional staff.
### Consistent brand voice
You can instruct Claude to consistently represent your brand's tone and values, whereas human agents may vary in their communication styles.
Some considerations for choosing Claude over other LLMs:
- You prioritize natural, nuanced conversation: Claude's sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.
- You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating canned responses or requiring extensive programming of permutations of user utterances.
- You need scalable multilingual support: Claude's multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.
### Define your ideal chat interaction
Outline an ideal customer interaction to define how and when you expect the customer to interact with Claude. This outline will help to determine the technical requirements of your solution.
Here is an example chat interaction for car insurance customer support:
- **Customer:** Initiates support chat experience
- **Claude:** Warmly greets customer and initiates conversation
- **Customer:** Asks about insurance for their new electric car
- **Claude:** Provides relevant information about electric vehicle coverage
- **Customer:** Asks questions related to unique needs for electric vehicle insurances
- **Claude:** Responds with accurate and informative answers and provides links to the sources
- **Customer:** Asks off-topic questions unrelated to insurance or cars
- **Claude:** Clarifies it does not discuss unrelated topics and steers the user back to car insurance
- **Customer:** Expresses interest in an insurance quote
- **Claude:** Ask a set of questions to determine the appropriate quote, adapting to their responses
- **Claude:** Sends a request to use the quote generation API tool along with necessary information collected from the user
- **Claude:** Receives the response information from the API tool use, synthesizes the information into a natural response, and presents the provided quote to the user
- **Customer:** Asks follow up questions
- **Claude:** Answers follow up questions as needed
- **Claude:** Guides the customer to the next steps in the insurance process and closes out the conversation
In the real example that you write for your own use case, you might find it useful to write out the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.
### Break the interaction into unique tasks
Customer support chat is a collection of multiple different tasks, from question answering to information retrieval to taking action on requests, wrapped up in a single customer interaction. Before you start building, break down your ideal customer interaction into every task you want Claude to be able to perform. This ensures you can prompt and evaluate Claude for every task, and gives you a good sense of the range of interactions you need to account for when writing test cases.
Customers sometimes find it helpful to visualize this as an interaction flowchart of possible conversation inflection points depending on user requests.
Here are the key tasks associated with the example insurance interaction:
1. Greeting and general guidance
- Warmly greet the customer and initiate conversation
- Provide general information about the company and interaction
2. Product information
- Provide information about electric vehicle coverage
This will require that Claude have the necessary information in its context, and might imply that a [RAG integration](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) is necessary.
- Answer questions related to unique electric vehicle insurance needs
- Answer follow-up questions about the quote or insurance details
- Offer links to sources when appropriate
3. Conversation management
- Stay on topic (car insurance)
- Redirect off-topic questions back to relevant subjects
4. Quote generation
- Ask appropriate questions to determine quote eligibility
- Adapt questions based on customer responses
- Submit collected information to quote generation API
- Present the provided quote to the customer
### Establish success criteria
Work with your support team to [define success criteria and write detailed evaluations](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks and goals.
Here are criteria and benchmarks that can be used to evaluate how successfully Claude performs the defined tasks:
### Query comprehension accuracy
This metric evaluates how accurately Claude understands customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95% or higher.
### Response relevance
This assesses how well Claude's response addresses the customer's specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90% or above.
### Response accuracy
Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100% accuracy in this introductory information.
### Citation provision relevance
Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80% of interactions where additional information could be beneficial.
### Topic adherence
Measure how well Claude stays on topic, such as the topic of car insurance in the example implementation. Aim for 95% of responses to be directly related to car insurance or the customer's specific query.
### Content generation effectiveness
Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude understands when to generate a quote and how accurate that quote is. Target 100% accuracy, as this is vital information for a successful customer interaction.
### Escalation efficiency
This measures Claude's ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren't. Aim for an escalation accuracy of 95% or higher.
Here are criteria and benchmarks that can be used to evaluate the business impact of employing Claude for support:
### Sentiment maintenance
This assesses Claude's ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90% of interactions.
### Deflection rate
The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for 70-80% deflection rate, depending on the complexity of inquiries.
### Customer satisfaction score
A measure of how satisfied customers are with their chatbot interaction. Usually done through post-interaction surveys. Aim for a CSAT score of 4 out of 5 or higher.
### Average handle time
The average time it takes for the chatbot to resolve an inquiry. This varies widely based on the complexity of issues, but generally, aim for a lower AHT compared to human agents.
## How to implement Claude as a customer service agent
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
For customer support chat, Claude Opus 5 is well suited to balance intelligence, latency, and cost, including the most complex support scenarios that require deep reasoning across long, multi-step conversations. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, or long-context prompts, Claude Haiku 4.5 may be more suitable to optimize for latency.
### Build a strong prompt
Using Claude for customer support requires Claude having enough direction and context to respond appropriately, while having enough flexibility to handle a wide range of customer inquiries.
Start by writing the elements of a strong prompt, beginning with a system prompt. Create a file called `config.py` and add each of the following blocks to it:
```python
IDENTITY = """You are Eva, a friendly and knowledgeable AI assistant for Acme Insurance
Company. Your role is to warmly welcome customers and provide information on
Acme's insurance offerings, which include car insurance and electric car
insurance. You can also help customers get quotes for their insurance needs."""
```
While you may be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first `User` turn (with the only exception being role prompting). Read more at [Giving Claude a role with a system prompt](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
It's best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step-by-step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you'll be writing piecemeal all the parts for a prompt starting with the "Greeting and general guidance" task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.
```python
STATIC_GREETINGS_AND_GENERAL = """
<static_context>
Acme Auto Insurance: Your Trusted Companion on the Road
About:
At Acme Insurance, we understand that your vehicle is more than just a mode of transportation—it's your ticket to life's adventures.
Since 1985, we've been crafting auto insurance policies that give drivers the confidence to explore, commute, and travel with peace of mind.
Whether you're navigating city streets or embarking on cross-country road trips, Acme is there to protect you and your vehicle.
Our innovative auto insurance policies are designed to adapt to your unique needs, covering everything from fender benders to major collisions.
With Acme's award-winning customer service and swift claim resolution, you can focus on the joy of driving while we handle the rest.
We're not just an insurance provider—we're your co-pilot in life's journeys.
Choose Acme Auto Insurance and experience the assurance that comes with superior coverage and genuine care. Because at Acme, we don't just
insure your car—we fuel your adventures on the open road.
Note: We also offer specialized coverage for electric vehicles, ensuring that drivers of all car types can benefit from our protection.
Acme Insurance offers the following products:
- Car insurance
- Electric car insurance
- Two-wheeler insurance
Business hours: Monday-Friday, 9 AM - 5 PM EST
Customer service number: 1-800-123-4567
</static_context>
"""
```
Then do the same for your car insurance and electric car insurance information.
```python
STATIC_CAR_INSURANCE = """
<static_context>
Car Insurance Coverage:
Acme's car insurance policies typically cover:
1. Liability coverage: Pays for bodily injury and property damage you cause to others.
2. Collision coverage: Pays for damage to your car in an accident.
3. Comprehensive coverage: Pays for damage to your car from non-collision incidents.
4. Medical payments coverage: Pays for medical expenses after an accident.
5. Uninsured/underinsured motorist coverage: Protects you if you're hit by a driver with insufficient insurance.
Optional coverages include:
- Rental car reimbursement
- Roadside assistance
- New car replacement
</static_context>
"""
STATIC_ELECTRIC_CAR_INSURANCE = """
<static_context>
Electric Car Insurance:
Our specialized electric car insurance goes beyond traditional auto coverage,
offering tailored protection for your high-tech investment. In addition to standard coverages, we offer:
- Safeguarding expensive battery systems
- Covering home charging equipment
- Adapting to the rapidly evolving world of electric vehicles
Whether you're driving a Rivian, Nissan Leaf, Chevrolet Bolt,
or any other electric vehicle, our knowledgeable agents are ready to craft a policy
that gives you the confidence to enjoy every electron-powered mile.
</static_context>
"""
```
Now that you have your static content, add at least 4-5 sample "good" interactions to guide Claude's responses. These examples should be representative of your ideal customer interaction and can include elements such as guardrails and tool calls.
```python
EXAMPLES = """
Here are a few examples of how you can interact with customers:
<example 1>
H: Hi, do you offer commercial insurance for small businesses?
A: Ah! Unfortunately, we don't offer commercial insurance at this time.
However, we do provide a range of personal insurance products including car insurance and electric car insurance.
Would you like to know more about these offerings?
</example 1>
<example 2>
H: Hi, what are your business hours?
A: Our business hours are Monday to Friday, 9 AM to 5 PM EST.
If you have any questions or need assistance, feel free to reach out during those times.
How else can I assist you today?
</example 2>
<example 3>
H: I'm shopping for car insurance. What does Acme offer?
A: Great choice! Acme's car insurance policies typically include:
- Liability coverage: Protects you if you're at fault in an accident
- Collision coverage: Pays for damage to your car in an accident
- Comprehensive coverage: Covers non-collision incidents like theft or vandalism
- Medical payments coverage: Pays for medical expenses after an accident
- Uninsured/underinsured motorist coverage: Protects you from drivers with insufficient insurance
We also offer optional coverages like rental car reimbursement, roadside assistance, and new car replacement.
Would you like more details on any of these coverages, or do you have specific questions about insuring your vehicle?
</example 3>
<example 4>
H: I'd like to hear about your electric car insurance.
A: Certainly! Our electric car insurance is specially designed to meet the unique needs of electric vehicle owners.
In addition to all the standard coverages we offer for regular cars, our electric car policies include:
- Battery coverage: Protection against damage or degradation of your vehicle's expensive battery system
- Tech package: Covers repairs or replacement of advanced electronics and onboard computer systems
- Charging station coverage: Protects both home and portable charging equipment
- Cybersecurity protection: Coverage against hacking or digital threats
- Specialized roadside assistance: Includes flatbed towing to protect the vehicle's undercarriage
We cover a wide range of electric vehicles, including popular models from Tesla, Rivian, Nissan, Chevrolet, and more.
Is there a specific electric vehicle you're looking to insure, or would you like more details on any of these coverages?
</example 4>
<example 5>
H: I'd like to get a quote for my car insurance.
A: Certainly! I'd be happy to help you get a quote for your car insurance.
To provide you with an accurate quote, I'll need to collect some information about your vehicle and the primary driver.
Let's start with the basics:
1. What is the make and model of your vehicle?
2. What year was it manufactured?
3. Approximately how many miles have you driven?
4. What is the age of the primary driver?
Once you provide this information, I'll use our quoting tool to generate a personalized insurance quote for you.
</example 5>
"""
```
You will also want to include any important instructions outlining dos and don'ts for how Claude should interact with the customer. This may draw from brand guardrails or support policies.
```python
ADDITIONAL_GUARDRAILS = """Please adhere to the following guardrails:
1. Only provide information about insurance types listed in our offerings.
2. If asked about an insurance type we don't offer, politely state
that we don't provide that service.
3. Do not speculate about future product offerings or company plans.
4. Don't make promises or enter into agreements it's not authorized to make.
You only provide information and guidance.
5. Do not mention any competitor's products or services.
"""
```
Now combine all these sections into a single string to use as your prompt.
```python
TASK_SPECIFIC_INSTRUCTIONS = " ".join(
[
STATIC_GREETINGS_AND_GENERAL,
STATIC_CAR_INSURANCE,
STATIC_ELECTRIC_CAR_INSURANCE,
EXAMPLES,
ADDITIONAL_GUARDRAILS,
]
)
```
### Add dynamic and agentic capabilities with tool use
Claude is capable of taking actions and retrieving information dynamically using client-side tool use functionality. Start by listing any external tools or APIs the prompt should use.
For this example, start with one tool for calculating the quote.
As a reminder, this tool will not perform the actual calculation, it will just signal to the application that a tool should be used with whatever arguments specified.
Add the model name, the tool definition, and a stub implementation to `config.py`:
```python
import time
MODEL = "claude-opus-5-5"
TOOLS = [
{
"name": "get_quote",
"description": "Calculate the insurance quote based on user input. Returned value is per month premium.",
"input_schema": {
"type": "object",
"properties": {
"make": {"type": "string", "description": "The make of the vehicle."},
"model": {"type": "string", "description": "The model of the vehicle."},
"year": {
"type": "integer",
"description": "The year the vehicle was manufactured.",
},
"mileage": {
"type": "integer",
"description": "The mileage on the vehicle.",
},
"driver_age": {
"type": "integer",
"description": "The age of the primary driver.",
},
},
"required": ["make", "model", "year", "mileage", "driver_age"],
},
}
]
def get_quote(make, model, year, mileage, driver_age):
"""Returns the premium per month in USD"""
# You can call an http endpoint or a database to get the quote.
# Here, we simulate a delay of 1 seconds and return a fixed quote of 100.
time.sleep(1)
return 100
```
### Deploy your prompts
It's hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests). Build a small application using the prompt, the Anthropic SDK, and Streamlit for a user interface.
In a file called `chatbot.py` (or the equivalent module in your language), set up the ChatBot class, which will encapsulate the interactions with the Anthropic SDK.
The class should have two main methods: one that calls the API to generate a message, and one that processes each incoming user input.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# In your chatbot.py, import these from the config.py you wrote above:
# from config import IDENTITY, TOOLS, MODEL, get_quote
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()
class ChatBot:
def __init__(self, session_state):
self.anthropic = Anthropic()
self.session_state = session_state
def generate_message(
self,
messages,
max_tokens,
):
try:
response = self.anthropic.messages.create(
model=MODEL,
system=IDENTITY,
max_tokens=max_tokens,
messages=messages,
tools=TOOLS,
)
return response
except Exception as e:
return {"error": str(e)}
def process_user_input(self, user_input):
self.session_state.messages.append({"role": "user", "content": user_input})
response_message = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in response_message:
return f"An error occurred: {response_message['error']}"
if response_message.content[-1].type == "tool_use":
tool_use = response_message.content[-1]
func_name = tool_use.name
func_params = tool_use.input
tool_use_id = tool_use.id
result = self.handle_tool_use(func_name, func_params)
self.session_state.messages.append(
{"role": "assistant", "content": response_message.content}
)
self.session_state.messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": f"{result}",
}
],
}
)
follow_up_response = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in follow_up_response:
return f"An error occurred: {follow_up_response['error']}"
response_text = next(
(block.text for block in follow_up_response.content if block.type == "text"),
None,
)
if response_text is None:
raise Exception("An error occurred: Unexpected response type")
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
text_block = next(
(block for block in response_message.content if block.type == "text"), None
)
if text_block is not None:
response_text = text_block.text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
raise Exception("An error occurred: Unexpected response type")
def handle_tool_use(self, func_name, func_params):
if func_name == "get_quote":
premium = get_quote(**func_params)
return f"Quote generated: ${premium:.2f} per month"
raise Exception("An unexpected tool was used")
```
### Build your user interface
Test deploying this code with Streamlit using a main method. This `main()` function sets up a Streamlit-based chat interface. Streamlit is a Python framework, so this part of the walkthrough is shown in Python only; the ChatBot class above is the piece you can port to any language.
Do this in a file called `app.py`
```python
import streamlit as st
from chatbot import ChatBot
from config import TASK_SPECIFIC_INSTRUCTIONS
def main():
st.title("Chat with Eva, Acme Insurance Company's Assistant🤖")
if "messages" not in st.session_state:
st.session_state.messages = [
{"role": "user", "content": TASK_SPECIFIC_INSTRUCTIONS},
{"role": "assistant", "content": "Understood"},
]
chatbot = ChatBot(st.session_state)
# Display user and assistant messages skipping the first two
for message in st.session_state.messages[2:]:
# ignore tool use blocks
if isinstance(message["content"], str):
with st.chat_message(message["role"]):
st.markdown(message["content"])
if user_msg := st.chat_input("Type your message here..."):
st.chat_message("user").markdown(user_msg)
with st.chat_message("assistant"):
with st.spinner("Eva is thinking..."):
response_placeholder = st.empty()
full_response = chatbot.process_user_input(user_msg)
response_placeholder.markdown(full_response)
if __name__ == "__main__":
main()
```
Run the program with:
```python
streamlit run app.py
```
### Evaluate your prompts
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the chatbot performance using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#build-evaluations) based on your defined success criteria will allow you to optimize your prompts.
### Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
#### Reduce long context latency with RAG
When dealing with large amounts of static and dynamic context, including all information in the prompt can lead to high costs, slower response times, and reaching context window limits. In this scenario, implementing Retrieval Augmented Generation (RAG) techniques can improve performance and efficiency.
By using [embedding models like Voyage](/docs/en/build-with-claude/embeddings) to convert information into vector representations, you can create a more scalable and responsive system. This approach allows for dynamic retrieval of relevant information based on the current query, rather than including all possible context in every prompt.
Implementing RAG for support use cases has been shown to increase accuracy, reduce response times, and reduce API costs in systems with extensive context requirements. See the [RAG recipe](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) for a worked example.
#### Integrate real-time data with tool use
When dealing with queries that require real-time information, such as account balances or policy details, embedding-based RAG approaches are not sufficient. Instead, tool use can enhance your chatbot's ability to provide accurate, real-time responses. For example, you can use tool use to look up customer information, retrieve order details, and cancel orders on behalf of the customer.
This approach, [outlined in the tool use: customer service agent recipe](https://platform.claude.com/cookbook/tool-use-customer-service-agent), lets you integrate live data into Claude's responses and provide a more personalized and efficient customer experience.
#### Strengthen input and output guardrails
When deploying a chatbot, especially in customer service scenarios, it's important to prevent risks associated with misuse, out-of-scope queries, and inappropriate responses. While Claude is inherently resilient to such scenarios, here are additional steps to strengthen your chatbot guardrails:
- [Reduce hallucination](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations): Implement fact-checking mechanisms and [citations](https://platform.claude.com/cookbook/misc-using-citations) to ground responses in provided information.
- Cross-check information: Verify that the agent's responses align with your company's policies and known facts.
- Avoid contractual commitments: Ensure the agent doesn't make promises or enter into agreements it's not authorized to make.
- [Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use methods like harmlessness screens and input validation to prevent users from exploiting model vulnerabilities, aiming to generate inappropriate content.
- Avoid mentioning competitors: Implement a competitor mention filter to maintain brand focus and not mention any competitor's products or services.
- [Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency): Prevent Claude from changing style or going out of character, even during long, complex interactions.
- Remove Personally Identifiable Information (PII): Unless explicitly required and authorized, strip out any PII from responses.
#### Reduce perceived response time with streaming
When dealing with potentially lengthy responses, implementing streaming can improve user engagement and satisfaction. In this scenario, users receive the answer progressively instead of waiting for the entire response to be generated.
Here is how to implement streaming:
1. Use the [Anthropic Streaming API](/docs/en/build-with-claude/streaming) to support streaming responses.
2. Set up your frontend to handle incoming chunks of text.
3. Display each chunk as it arrives, simulating real-time typing.
4. Implement a mechanism to save the full response, allowing users to view it if they navigate away and return.
In some cases, streaming enables the use of more advanced models with higher base latencies, as the progressive display mitigates the impact of longer processing times.
#### Scale your chatbot
As the complexity of your chatbot grows, your application architecture can evolve to match. Before you add further layers to your architecture, consider the following less exhaustive options:
- Ensure that you are making the most out of your prompts and optimizing through prompt engineering. Use the [prompt engineering guides](/docs/en/build-with-claude/prompt-engineering/overview) to write the most effective prompts.
- Add additional [tools](/docs/en/agents-and-tools/tool-use/overview) to the prompt (which can include [prompt chains](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#chain-complex-prompts)) and see if you can achieve the functionality required.
If your chatbot handles incredibly varied tasks, you may want to consider adding a [separate intent classifier](https://platform.claude.com/cookbook/capabilities-classification-guide) to route the initial customer query. For the existing application, this would involve creating a decision tree that would route customer queries through the classifier and then to specialized conversations (with their own set of tools and system prompts). Note, this method requires an additional call to Claude that can increase latency.
### Integrate Claude into your support workflow
While these examples have focused on Python functions callable within a Streamlit environment, deploying Claude for real-time support chatbot requires an API service.
Here's how you can approach this:
1. Create an API wrapper: Develop a simple API wrapper around your classification function. For example, you can use Flask API or Fast API to wrap your code into a HTTP Service. Your HTTP service could accept the user input and return the Assistant response in its entirety. Thus, your service could have the following characteristics:
- Server-Sent Events (SSE): SSE allows for real-time streaming of responses from the server to the client. This provides a smooth, interactive experience when working with LLMs.
- Caching: Implementing caching can improve response times and reduce unnecessary API calls.
- Context retention: Maintaining context when a user navigates away and returns is important for continuity in conversations.
2. Build a web interface: Implement a user-friendly web UI for interacting with the Claude-powered agent.
## Next steps
[Tool use](/docs/en/agents-and-tools/tool-use/overview)
Give Claude access to your APIs so it can take action on behalf of customers.
[Develop tests](/docs/en/test-and-evaluate/develop-tests)
Build evaluations to measure your support agent against the success criteria you defined.
[Streaming](/docs/en/build-with-claude/streaming)
Stream responses so customers see answers as they generate.
[Prompt engineering](/docs/en/build-with-claude/prompt-engineering/overview)
Refine your system prompt and examples for better task performance.
---
## About/about-claude-use-case-guides-customer-support-chat-5b82b8509b.md
# Customer support agent
This guide walks through how to leverage Claude's advanced conversational capabilities to handle customer inquiries in real time, providing 24/7 support, reducing wait times, and managing high support volumes with accurate responses and positive interactions.
---
## Before building with Claude
### Decide whether to use Claude for support chat
Here are some key indicators that you should employ an LLM like Claude to automate portions of your customer support process:
<section title="High volume of repetitive queries">
Claude excels at handling a large number of similar questions efficiently, freeing up human agents for more complex issues.
</section>
<section title="Need for quick information synthesis">
Claude can quickly retrieve, process, and combine information from vast knowledge bases, while human agents may need time to research or consult multiple sources.
</section>
<section title="24/7 availability requirement">
Claude can provide round-the-clock support without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
</section>
<section title="Rapid scaling during peak periods">
Claude can handle sudden increases in query volume without the need for hiring and training additional staff.
</section>
<section title="Consistent brand voice">
You can instruct Claude to consistently represent your brand's tone and values, whereas human agents may vary in their communication styles.
</section>
Some considerations for choosing Claude over other LLMs:
- You prioritize natural, nuanced conversation: Claude's sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.
- You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating canned responses or requiring extensive programming of permutations of user utterances.
- You need scalable multilingual support: Claude's multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.
### Define your ideal chat interaction
Outline an ideal customer interaction to define how and when you expect the customer to interact with Claude. This outline will help to determine the technical requirements of your solution.
Here is an example chat interaction for car insurance customer support:
* **Customer:** Initiates support chat experience
* **Claude:** Warmly greets customer and initiates conversation
* **Customer:** Asks about insurance for their new electric car
* **Claude:** Provides relevant information about electric vehicle coverage
* **Customer:** Asks questions related to unique needs for electric vehicle insurances
* **Claude:** Responds with accurate and informative answers and provides links to the sources
* **Customer:** Asks off-topic questions unrelated to insurance or cars
* **Claude:** Clarifies it does not discuss unrelated topics and steers the user back to car insurance
* **Customer:** Expresses interest in an insurance quote
* **Claude:** Ask a set of questions to determine the appropriate quote, adapting to their responses
* **Claude:** Sends a request to use the quote generation API tool along with necessary information collected from the user
* **Claude:** Receives the response information from the API tool use, synthesizes the information into a natural response, and presents the provided quote to the user
* **Customer:** Asks follow up questions
* **Claude:** Answers follow up questions as needed
* **Claude:** Guides the customer to the next steps in the insurance process and closes out the conversation
<Tip>In the real example that you write for your own use case, you might find it useful to write out the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.</Tip>
### Break the interaction into unique tasks
Customer support chat is a collection of multiple different tasks, from question answering to information retrieval to taking action on requests, wrapped up in a single customer interaction. Before you start building, break down your ideal customer interaction into every task you want Claude to be able to perform. This ensures you can prompt and evaluate Claude for every task, and gives you a good sense of the range of interactions you need to account for when writing test cases.
<Tip>Customers sometimes find it helpful to visualize this as an interaction flowchart of possible conversation inflection points depending on user requests.</Tip>
Here are the key tasks associated with the example insurance interaction above:
1. Greeting and general guidance
- Warmly greet the customer and initiate conversation
- Provide general information about the company and interaction
2. Product Information
- Provide information about electric vehicle coverage
<Note>This will require that Claude have the necessary information in its context, and might imply that a [RAG integration](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) is necessary.</Note>
- Answer questions related to unique electric vehicle insurance needs
- Answer follow-up questions about the quote or insurance details
- Offer links to sources when appropriate
3. Conversation Management
- Stay on topic (car insurance)
- Redirect off-topic questions back to relevant subjects
4. Quote Generation
- Ask appropriate questions to determine quote eligibility
- Adapt questions based on customer responses
- Submit collected information to quote generation API
- Present the provided quote to the customer
### Establish success criteria
Work with your support team to [define success criteria and write detailed evaluations](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks and goals.
Here are criteria and benchmarks that can be used to evaluate how successfully Claude performs the defined tasks:
<section title="Query comprehension accuracy">
This metric evaluates how accurately Claude understands customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95% or higher.
</section>
<section title="Response relevance">
This assesses how well Claude's response addresses the customer's specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90% or above.
</section>
<section title="Response accuracy">
Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100% accuracy in this introductory information.
</section>
<section title="Citation provision relevance">
Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80% of interactions where additional information could be beneficial.
</section>
<section title="Topic adherence">
Measure how well Claude stays on topic, such as the topic of car insurance in the example implementation. Aim for 95% of responses to be directly related to car insurance or the customer's specific query.
</section>
<section title="Content generation effectiveness">
Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude understands when to generate a quote and how accurate that quote is. Target 100% accuracy, as this is vital information for a successful customer interaction.
</section>
<section title="Escalation efficiency">
This measures Claude's ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren't. Aim for an escalation accuracy of 95% or higher.
</section>
Here are criteria and benchmarks that can be used to evaluate the business impact of employing Claude for support:
<section title="Sentiment maintenance">
This assesses Claude's ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90% of interactions.
</section>
<section title="Deflection rate">
The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for 70-80% deflection rate, depending on the complexity of inquiries.
</section>
<section title="Customer satisfaction score">
A measure of how satisfied customers are with their chatbot interaction. Usually done through post-interaction surveys. Aim for a CSAT score of 4 out of 5 or higher.
</section>
<section title="Average handle time">
The average time it takes for the chatbot to resolve an inquiry. This varies widely based on the complexity of issues, but generally, aim for a lower AHT compared to human agents.
</section>
## How to implement Claude as a customer service agent
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
For customer support chat, Claude Opus 4.7 is well suited to balance intelligence, latency, and cost. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, and/or long-context prompts, Claude Haiku 4.5 may be more suitable to optimize for latency.
### Build a strong prompt
Using Claude for customer support requires Claude having enough direction and context to respond appropriately, while having enough flexibility to handle a wide range of customer inquiries.
Start by writing the elements of a strong prompt, starting with a system prompt:
```python
IDENTITY = """You are Eva, a friendly and knowledgeable AI assistant for Acme Insurance
Company. Your role is to warmly welcome customers and provide information on
Acme's insurance offerings, which include car insurance and electric car
insurance. You can also help customers get quotes for their insurance needs."""
```
<Tip>While you may be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first `User` turn (with the only exception being role prompting). Read more at [Giving Claude a role with a system prompt](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).</Tip>
It's best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step by step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you'll be writing piecemeal all the parts for a prompt starting with the "Greeting and general guidance" task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.
Put all of these pieces in a file called `config.py`.
```python
STATIC_GREETINGS_AND_GENERAL = """
<static_context>
Acme Auto Insurance: Your Trusted Companion on the Road
About:
At Acme Insurance, we understand that your vehicle is more than just a mode of transportation—it's your ticket to life's adventures.
Since 1985, we've been crafting auto insurance policies that give drivers the confidence to explore, commute, and travel with peace of mind.
Whether you're navigating city streets or embarking on cross-country road trips, Acme is there to protect you and your vehicle.
Our innovative auto insurance policies are designed to adapt to your unique needs, covering everything from fender benders to major collisions.
With Acme's award-winning customer service and swift claim resolution, you can focus on the joy of driving while we handle the rest.
We're not just an insurance provider—we're your co-pilot in life's journeys.
Choose Acme Auto Insurance and experience the assurance that comes with superior coverage and genuine care. Because at Acme, we don't just
insure your car—we fuel your adventures on the open road.
Note: We also offer specialized coverage for electric vehicles, ensuring that drivers of all car types can benefit from our protection.
Acme Insurance offers the following products:
- Car insurance
- Electric car insurance
- Two-wheeler insurance
Business hours: Monday-Friday, 9 AM - 5 PM EST
Customer service number: 1-800-123-4567
</static_context>
"""
```
Then do the same for your car insurance and electric car insurance information.
```python
STATIC_CAR_INSURANCE = """
<static_context>
Car Insurance Coverage:
Acme's car insurance policies typically cover:
1. Liability coverage: Pays for bodily injury and property damage you cause to others.
2. Collision coverage: Pays for damage to your car in an accident.
3. Comprehensive coverage: Pays for damage to your car from non-collision incidents.
4. Medical payments coverage: Pays for medical expenses after an accident.
5. Uninsured/underinsured motorist coverage: Protects you if you're hit by a driver with insufficient insurance.
Optional coverages include:
- Rental car reimbursement
- Roadside assistance
- New car replacement
</static_context>
"""
STATIC_ELECTRIC_CAR_INSURANCE = """
<static_context>
Electric Car Insurance:
Our specialized electric car insurance goes beyond traditional auto coverage,
offering tailored protection for your high-tech investment. In addition to standard coverages, we offer:
- Safeguarding expensive battery systems
- Covering home charging equipment
- Adapting to the rapidly evolving world of electric vehicles
Whether you're driving a Rivian, Nissan Leaf, Chevrolet Bolt,
or any other electric vehicle, our knowledgeable agents are ready to craft a policy
that gives you the confidence to enjoy every electron-powered mile.
</static_context>
"""
```
Now that you have your static content, add at least 4-5 sample "good" interactions to guide Claude's responses. These examples should be representative of your ideal customer interaction and can include guardrails, tool calls, etc.
```python
EXAMPLES = """
Here are a few examples of how you can interact with customers:
<example 1>
H: Hi, do you offer commercial insurance for small businesses?
A: Ah! Unfortunately, we don't offer commercial insurance at this time.
However, we do provide a range of personal insurance products including car insurance and electric car insurance.
Would you like to know more about these offerings?
</example 1>
<example 2>
H: Hi, what are your business hours?
A: Our business hours are Monday to Friday, 9 AM to 5 PM EST.
If you have any questions or need assistance, feel free to reach out during those times.
How else can I assist you today?
</example 2>
<example 3>
H: I'm shopping for car insurance. What does Acme offer?
A: Great choice! Acme's car insurance policies typically include:
- Liability coverage: Protects you if you're at fault in an accident
- Collision coverage: Pays for damage to your car in an accident
- Comprehensive coverage: Covers non-collision incidents like theft or vandalism
- Medical payments coverage: Pays for medical expenses after an accident
- Uninsured/underinsured motorist coverage: Protects you from drivers with insufficient insurance
We also offer optional coverages like rental car reimbursement, roadside assistance, and new car replacement.
Would you like more details on any of these coverages, or do you have specific questions about insuring your vehicle?
</example 3>
<example 4>
H: I'd like to hear about your electric car insurance.
A: Certainly! Our electric car insurance is specially designed to meet the unique needs of electric vehicle owners.
In addition to all the standard coverages we offer for regular cars, our electric car policies include:
- Battery coverage: Protection against damage or degradation of your vehicle's expensive battery system
- Tech package: Covers repairs or replacement of advanced electronics and onboard computer systems
- Charging station coverage: Protects both home and portable charging equipment
- Cybersecurity protection: Coverage against hacking or digital threats
- Specialized roadside assistance: Includes flatbed towing to protect the vehicle's undercarriage
We cover a wide range of electric vehicles, including popular models from Tesla, Rivian, Nissan, Chevrolet, and more.
Is there a specific electric vehicle you're looking to insure, or would you like more details on any of these coverages?
</example 4>
<example 5>
H: I'd like to get a quote for my car insurance.
A: Certainly! I'd be happy to help you get a quote for your car insurance.
To provide you with an accurate quote, I'll need to collect some information about your vehicle and the primary driver.
Let's start with the basics:
1. What is the make and model of your vehicle?
2. What year was it manufactured?
3. Approximately how many miles have you driven?
4. What is the age of the primary driver?
Once you provide this information, I'll use our quoting tool to generate a personalized insurance quote for you.
</example 5>
"""
```
You will also want to include any important instructions outlining Do's and Don'ts for how Claude should interact with the customer.
This may draw from brand guardrails or support policies.
```python
ADDITIONAL_GUARDRAILS = """Please adhere to the following guardrails:
1. Only provide information about insurance types listed in our offerings.
2. If asked about an insurance type we don't offer, politely state
that we don't provide that service.
3. Do not speculate about future product offerings or company plans.
4. Don't make promises or enter into agreements it's not authorized to make.
You only provide information and guidance.
5. Do not mention any competitor's products or services.
"""
```
Now combine all these sections into a single string to use as your prompt.
```python nocheck
TASK_SPECIFIC_INSTRUCTIONS = " ".join(
[
STATIC_GREETINGS_AND_GENERAL,
STATIC_CAR_INSURANCE,
STATIC_ELECTRIC_CAR_INSURANCE,
EXAMPLES,
ADDITIONAL_GUARDRAILS,
]
)
```
### Add dynamic and agentic capabilities with tool use
Claude is capable of taking actions and retrieving information dynamically using client-side tool use functionality. Start by listing any external tools or APIs the prompt should utilize.
For this example, start with one tool for calculating the quote.
<Tip>As a reminder, this tool will not perform the actual calculation, it will just signal to the application that a tool should be used with whatever arguments specified.</Tip>
Example insurance quote calculator:
```python
TOOLS = [
{
"name": "get_quote",
"description": "Calculate the insurance quote based on user input. Returned value is per month premium.",
"input_schema": {
"type": "object",
"properties": {
"make": {"type": "string", "description": "The make of the vehicle."},
"model": {"type": "string", "description": "The model of the vehicle."},
"year": {
"type": "integer",
"description": "The year the vehicle was manufactured.",
},
"mileage": {
"type": "integer",
"description": "The mileage on the vehicle.",
},
"driver_age": {
"type": "integer",
"description": "The age of the primary driver.",
},
},
"required": ["make", "model", "year", "mileage", "driver_age"],
},
}
]
def get_quote(make, model, year, mileage, driver_age):
"""Returns the premium per month in USD"""
# You can call an http endpoint or a database to get the quote.
# Here, we simulate a delay of 1 seconds and return a fixed quote of 100.
time.sleep(1)
return 100
```
### Deploy your prompts
It's hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests) so let's build a small application using the prompt, the Anthropic SDK, and streamlit for a user interface.
In a file called `chatbot.py`, start by setting up the ChatBot class, which will encapsulate the interactions with the Anthropic SDK.
The class should have two main methods: `generate_message` and `process_user_input`.
```python nocheck
from anthropic import Anthropic
from config import IDENTITY, TOOLS, MODEL, get_quote
from dotenv import load_dotenv
load_dotenv()
class ChatBot:
def __init__(self, session_state):
self.anthropic = Anthropic()
self.session_state = session_state
def generate_message(
self,
messages,
max_tokens,
):
try:
response = self.anthropic.messages.create(
model=MODEL,
system=IDENTITY,
max_tokens=max_tokens,
messages=messages,
tools=TOOLS,
)
return response
except Exception as e:
return {"error": str(e)}
def process_user_input(self, user_input):
self.session_state.messages.append({"role": "user", "content": user_input})
response_message = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in response_message:
return f"An error occurred: {response_message['error']}"
if response_message.content[-1].type == "tool_use":
tool_use = response_message.content[-1]
func_name = tool_use.name
func_params = tool_use.input
tool_use_id = tool_use.id
result = self.handle_tool_use(func_name, func_params)
self.session_state.messages.append(
{"role": "assistant", "content": response_message.content}
)
self.session_state.messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_id,
"content": f"{result}",
}
],
}
)
follow_up_response = self.generate_message(
messages=self.session_state.messages,
max_tokens=2048,
)
if "error" in follow_up_response:
return f"An error occurred: {follow_up_response['error']}"
response_text = follow_up_response.content[0].text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
elif response_message.content[0].type == "text":
response_text = response_message.content[0].text
self.session_state.messages.append(
{"role": "assistant", "content": response_text}
)
return response_text
else:
raise Exception("An error occurred: Unexpected response type")
def handle_tool_use(self, func_name, func_params):
if func_name == "get_quote":
premium = get_quote(**func_params)
return f"Quote generated: ${premium:.2f} per month"
raise Exception("An unexpected tool was used")
```
### Build your user interface
Test deploying this code with Streamlit using a main method. This `main()` function sets up a Streamlit-based chat interface.
Do this in a file called `app.py`
```python nocheck
import streamlit as st
from chatbot import ChatBot
from config import TASK_SPECIFIC_INSTRUCTIONS
def main():
st.title("Chat with Eva, Acme Insurance Company's Assistant🤖")
if "messages" not in st.session_state:
st.session_state.messages = [
{"role": "user", "content": TASK_SPECIFIC_INSTRUCTIONS},
{"role": "assistant", "content": "Understood"},
]
chatbot = ChatBot(st.session_state)
# Display user and assistant messages skipping the first two
for message in st.session_state.messages[2:]:
# ignore tool use blocks
if isinstance(message["content"], str):
with st.chat_message(message["role"]):
st.markdown(message["content"])
if user_msg := st.chat_input("Type your message here..."):
st.chat_message("user").markdown(user_msg)
with st.chat_message("assistant"):
with st.spinner("Eva is thinking..."):
response_placeholder = st.empty()
full_response = chatbot.process_user_input(user_msg)
response_placeholder.markdown(full_response)
if __name__ == "__main__":
main()
```
Run the program with:
```bash
streamlit run app.py
```
### Evaluate your prompts
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the chatbot performance using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#building-evals-and-test-cases) based on your defined success criteria will allow you to optimize your prompts.
<Tip>The [Claude Console](/dashboard) now features an Evaluation tool that allows you to test your prompts under various scenarios.</Tip>
### Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
#### Reduce long context latency with RAG
When dealing with large amounts of static and dynamic context, including all information in the prompt can lead to high costs, slower response times, and reaching context window limits. In this scenario, implementing Retrieval Augmented Generation (RAG) techniques can significantly improve performance and efficiency.
By using [embedding models like Voyage](/docs/en/build-with-claude/embeddings) to convert information into vector representations, you can create a more scalable and responsive system. This approach allows for dynamic retrieval of relevant information based on the current query, rather than including all possible context in every prompt.
Implementing RAG for support use cases [RAG recipe](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide) has been shown to increase accuracy, reduce response times, and reduce API costs in systems with extensive context requirements.
#### Integrate real-time data with tool use
When dealing with queries that require real-time information, such as account balances or policy details, embedding-based RAG approaches are not sufficient. Instead, you can leverage tool use to significantly enhance your chatbot's ability to provide accurate, real-time responses. For example, you can use tool use to look up customer information, retrieve order details, and cancel orders on behalf of the customer.
This approach, [outlined in the tool use: customer service agent recipe](https://platform.claude.com/cookbook/tool-use-customer-service-agent), allows you to seamlessly integrate live data into your Claude's responses and provide a more personalized and efficient customer experience.
#### Strengthen input and output guardrails
When deploying a chatbot, especially in customer service scenarios, it's crucial to prevent risks associated with misuse, out-of-scope queries, and inappropriate responses. While Claude is inherently resilient to such scenarios, here are additional steps to strengthen your chatbot guardrails:
- [Reduce hallucination](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations): Implement fact-checking mechanisms and [citations](https://platform.claude.com/cookbook/misc-using-citations) to ground responses in provided information.
- Cross-check information: Verify that the agent's responses align with your company's policies and known facts.
- Avoid contractual commitments: Ensure the agent doesn't make promises or enter into agreements it's not authorized to make.
- [Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use methods like harmlessness screens and input validation to prevent users from exploiting model vulnerabilities, aiming to generate inappropriate content.
- Avoid mentioning competitors: Implement a competitor mention filter to maintain brand focus and not mention any competitor's products or services.
- [Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency): Prevent Claude from changing style or going out of character, even during long, complex interactions.
- Remove Personally Identifiable Information (PII): Unless explicitly required and authorized, strip out any PII from responses.
#### Reduce perceived response time with streaming
When dealing with potentially lengthy responses, implementing streaming can significantly improve user engagement and satisfaction. In this scenario, users receive the answer progressively instead of waiting for the entire response to be generated.
Here is how to implement streaming:
1. Use the [Anthropic Streaming API](/docs/en/build-with-claude/streaming) to support streaming responses.
2. Set up your frontend to handle incoming chunks of text.
3. Display each chunk as it arrives, simulating real-time typing.
4. Implement a mechanism to save the full response, allowing users to view it if they navigate away and return.
In some cases, streaming enables the use of more advanced models with higher base latencies, as the progressive display mitigates the impact of longer processing times.
#### Scale your Chatbot
As the complexity of your Chatbot grows, your application architecture can evolve to match. Before you add further layers to your architecture, consider the following less exhaustive options:
- Ensure that you are making the most out of your prompts and optimizing through prompt engineering. Use the [prompt engineering guides](/docs/en/build-with-claude/prompt-engineering/overview) to write the most effective prompts.
- Add additional [tools](/docs/en/build-with-claude/tool-use) to the prompt (which can include [prompt chains](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#chain-complex-prompts)) and see if you can achieve the functionality required.
If your Chatbot handles incredibly varied tasks, you may want to consider adding a [separate intent classifier](https://platform.claude.com/cookbook/capabilities-classification-guide) to route the initial customer query. For the existing application, this would involve creating a decision tree that would route customer queries through the classifier and then to specialized conversations (with their own set of tools and system prompts). Note, this method requires an additional call to Claude that can increase latency.
### Integrate Claude into your support workflow
While the examples above have focused on Python functions callable within a Streamlit environment, deploying Claude for real-time support chatbot requires an API service.
Here's how you can approach this:
1. Create an API wrapper: Develop a simple API wrapper around your classification function. For example, you can use Flask API or Fast API to wrap your code into a HTTP Service. Your HTTP service could accept the user input and return the Assistant response in its entirety. Thus, your service could have the following characteristics:
- Server-Sent Events (SSE): SSE allows for real-time streaming of responses from the server to the client. This is crucial for providing a smooth, interactive experience when working with LLMs.
- Caching: Implementing caching can significantly improve response times and reduce unnecessary API calls.
- Context retention: Maintaining context when a user navigates away and returns is important for continuity in conversations.
2. Build a web interface: Implement a user-friendly web UI for interacting with the Claude-powered agent.
<CardGroup cols={2}>
<Card title="Retrieval Augmented Generation (RAG) cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide">
Visit the RAG cookbook recipe for more example code and detailed guidance.
</Card>
<Card title="Citations cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
Explore the Citations cookbook recipe for how to ensure accuracy and explainability of information.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-legal-summarization-0b045c60ad.md
# Legal summarization
This guide walks through how to leverage Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
---
> Visit the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide) to see an example legal summarization implementation using Claude.
## Before building with Claude
### Decide whether to use Claude for legal summarization
Here are some key indicators that you should employ an LLM like Claude to summarize legal documents:
<section title="You want to review a high volume of documents efficiently and affordably">
Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks like due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
</section>
<section title="You require automated extraction of key metadata">
Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It's especially useful for contract management, compliance checks, or creating searchable databases of legal information.
</section>
<section title="You want to generate clear, concise, and standardized summaries">
Claude can generate structured summaries that follow predetermined formats, making it easier for legal professionals to quickly grasp the key points of various documents. These standardized summaries can improve readability, facilitate comparison between documents, and enhance overall comprehension, especially when dealing with complex legal language or technical jargon.
</section>
<section title="You need precise citations for your summaries">
When creating legal summaries, proper attribution and citation are crucial to ensure credibility and compliance with legal standards. Claude can be prompted to include accurate citations for all referenced legal points, making it easier for legal professionals to review and verify the summarized information.
</section>
<section title="You want to streamline and expedite your legal research process">
Claude can assist in legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
</section>
### Determine the details you want the summarization to extract
There is no single correct summary for any given document. Without clear direction, it can be difficult for Claude to determine which details to include. To achieve optimal results, identify the specific information you want to include in the summary.
For instance, when summarizing a sublease agreement, you might wish to extract the following key points:
```python
details_to_extract = [
"Parties involved (sublessor, sublessee, and original lessor)",
"Property details (address, description, and permitted use)",
"Term and rent (start date, end date, monthly rent, and security deposit)",
"Responsibilities (utilities, maintenance, and repairs)",
"Consent and notices (landlord's consent, and notice requirements)",
"Special provisions (furniture, parking, and subletting restrictions)",
]
```
### Establish success criteria
Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you may wish to consider when assessing how well Claude performs legal summarization.
<section title="Factual correctness">
The summary should accurately represent the facts, legal concepts, and key points in the document.
</section>
<section title="Legal precision">
Terminology and references to statutes, case law, or regulations must be correct and aligned with legal standards.
</section>
<section title="Conciseness">
The summary should condense the legal document to its essential points without losing important details.
</section>
<section title="Consistency">
If summarizing multiple documents, the LLM should maintain a consistent structure and approach to each summary.
</section>
<section title="Readability">
The text should be clear and easy to understand. If the audience is not legal experts, the summarization should not include legal jargon that could confuse the audience.
</section>
<section title="Bias and fairness">
The summary should present an unbiased and fair depiction of the legal arguments and positions.
</section>
See the guide on [establishing success criteria](/docs/en/test-and-evaluate/develop-tests) for more information.
---
## How to summarize legal documents using Claude
### Select the right Claude model
Model accuracy is extremely important when summarizing legal documents. Claude Opus 4.7 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents is large such that costs start to become a concern, you can also try using a smaller model like Claude Haiku 4.5.
To help estimate these costs, below is a comparison of the cost to summarize 1,000 sublease agreements using both Sonnet and Haiku:
* **Content size**
* Number of agreements: 1,000
* Characters per agreement: 300,000
* Total characters: 300M
* **Estimated tokens**
* Input tokens: 86M (assuming 1 token per 3.5 characters)
* Output tokens per summary: 350
* Total output tokens: 350,000
* **Claude Opus 4.7 estimated cost**
* Input token cost: 86 MTok * \$5.00/MTok = \$430
* Output token cost: 0.35 MTok * \$25.00/MTok = \$8.75
* Total cost: \$430.00 + \$8.75 = \$438.75
* **Claude Haiku 4.5 estimated cost**
* Input token cost: 86 MTok * \$1.00/MTok = \$86.00
* Output token cost: 0.35 MTok * \$5.00/MTok = \$1.75
* Total cost: \$86.00 + \$1.75 = \$87.75
<Tip>Actual costs may differ from these estimates. These estimates are based on the example highlighted in the section on [prompting](#build-a-strong-prompt).</Tip>
### Transform documents into a format that Claude can process
Before you begin summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it's ready to be processed by Claude.
Here is a demonstration of this process on a sample pdf:
```python nocheck
from io import BytesIO
import re
import pypdf
import requests
def get_llm_text(pdf_file):
reader = pypdf.PdfReader(pdf_file)
text = "\n".join([page.extract_text() for page in reader.pages])
# Remove extra whitespace
text = re.sub(r"\s+", " ", text)
# Remove page numbers
text = re.sub(r"\n\s*\d+\s*\n", "\n", text)
return text
# Create the full URL from the GitHub repository
url = "https://raw.githubusercontent.com/anthropics/anthropic-cookbook/main/skills/summarization/data/Sample Sublease Agreement.pdf"
url = url.replace(" ", "%20")
# Download the PDF file into memory
response = requests.get(url)
# Load the PDF from memory
pdf_file = BytesIO(response.content)
document_text = get_llm_text(pdf_file)
print(document_text[:50000])
```
In this example, you first download a pdf of a sample sublease agreement used in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).
The example uses the pypdf library to extract the contents of the pdf and convert it to text. The text data is then cleaned by removing extra whitespace and page numbers.
### Build a strong prompt
Claude can adapt to various summarization styles. You can change the details of the prompt to guide Claude to be more or less verbose, include more or less technical terminology, or provide a higher or lower level summary of the context at hand.
Here’s an example of how to create a prompt that ensures the generated summaries follow a consistent structure when analyzing sublease agreements:
```python Python nocheck hidelines={1..2}
import anthropic
# Initialize the Anthropic client
client = anthropic.Anthropic()
def summarize_document(
text, details_to_extract, model="claude-opus-4-7", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Prompt the model to summarize the sublease agreement
prompt = f"""Summarize the following sublease agreement. Focus on these key aspects:
{details_to_extract_str}
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
Sublease agreement text:
{text}
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal analyst specializing in real estate law, known for highly accurate and detailed summaries of sublease agreements.",
messages=[
{"role": "user", "content": prompt},
],
)
return response.content[0].text
sublease_summary = summarize_document(document_text, details_to_extract)
print(sublease_summary)
```
This code implements a `summarize_document` function that uses Claude to summarize the contents of a sublease agreement. The function accepts a text string and a list of details to extract as inputs. In this example, the code calls the function with the `document_text` and `details_to_extract` variables that were defined in the previous code snippets.
Within the function, a prompt is generated for Claude, including the document to be summarized, the details to extract, and specific instructions for summarizing the document. The prompt instructs Claude to respond with a summary of each detail to extract nested within XML headers.
Because the code outputs each section of the summary within tags, each section can easily be parsed out as a post-processing step. This approach enables structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
### Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#building-evals-and-test-cases) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you may wish to include within your empirical evaluation:
<section title="ROUGE scores">
This measures the overlap between the generated summary and an expert-created reference summary. This metric primarily focuses on recall and is useful for evaluating content coverage.
</section>
<section title="BLEU scores">
While originally developed for machine translation, this metric can be adapted for summarization tasks. BLEU scores measure the precision of n-gram matches between the generated summary and reference summaries. A higher score indicates that the generated summary contains similar phrases and terminology to the reference summary.
</section>
<section title="Contextual embedding similarity">
This metric involves creating vector representations (embeddings) of both the generated and reference summaries. The similarity between these embeddings is then calculated, often using cosine similarity. Higher similarity scores indicate that the generated summary captures the semantic meaning and context of the reference summary, even if the exact wording differs.
</section>
<section title="LLM-based grading">
This method involves using an LLM such as Claude to evaluate the quality of generated summaries against a scoring rubric. The rubric can be tailored to your specific needs, assessing key factors like accuracy, completeness, and coherence. For guidance on implementing LLM-based grading, view these [tips](/docs/en/test-and-evaluate/develop-tests#tips-for-llm-based-grading).
</section>
<section title="Human evaluation">
In addition to creating the reference summaries, legal experts can also evaluate the quality of the generated summaries. While this is expensive and time-consuming at scale, this is often done on a few summaries as a sanity check before deploying to production.
</section>
### Deploy your prompt
Here are some additional considerations to keep in mind as you deploy your solution to production.
1. **Ensure no liability:** Understand the legal implications of errors in the summaries, which could lead to legal liability for your organization or clients. Provide disclaimers or legal notices clarifying that the summaries are generated by AI and should be reviewed by legal professionals.
2. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real-world, documents may come in a variety of formats (PDFs, Word documents, text files, etc.). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
3. **Parallelize API calls to Claude:** Long documents with a large number of tokens may require up to a minute for Claude to generate a summary. For large document collections, you may want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](/docs/en/api/rate-limits#rate-limits) to determine the maximum amount of API calls that can be performed in parallel.
---
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Perform meta-summarization to summarize long documents
Legal summarization often involves handling long documents or many related documents at once, such that you surpass Claude’s context window. You can use a chunking method known as meta-summarization in order to handle this use case. This technique involves breaking down documents into smaller, manageable chunks and then processing each chunk separately. You can then combine the summaries of each chunk to create a meta-summary of the entire document.
Here's an example of how to perform meta-summarization:
```python Python nocheck hidelines={1..2}
import anthropic
# Initialize the Anthropic client
client = anthropic.Anthropic()
def chunk_text(text, chunk_size=20000):
return [text[i : i + chunk_size] for i in range(0, len(text), chunk_size)]
def summarize_long_document(
text, details_to_extract, model="claude-opus-4-7", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Iterate over chunks and summarize each one
chunk_summaries = [
summarize_document(
chunk, details_to_extract, model=model, max_tokens=max_tokens
)
for chunk in chunk_text(text)
]
final_summary_prompt = f"""
You are looking at the chunked summaries of multiple documents that are all related.
Combine the following summaries of the document from different truthful sources into a coherent overall summary:
<chunked_summaries>
{"".join(chunk_summaries)}
</chunked_summaries>
Focus on these key aspects:
{details_to_extract_str})
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal expert that summarizes notes on one document.",
messages=[
{"role": "user", "content": final_summary_prompt},
],
)
return response.content[0].text
long_summary = summarize_long_document(document_text, details_to_extract)
print(long_summary)
```
The `summarize_long_document` function builds upon the earlier `summarize_document` function by splitting the document into smaller chunks and summarizing each chunk individually.
The code achieves this by applying the `summarize_document` function to each chunk of 20,000 characters within the original document. The individual summaries are then combined, and a final summary is created from these chunk summaries.
Note that the `summarize_long_document` function isn't strictly necessary for the example pdf, as the entire document fits within Claude's context window. However, it becomes essential for documents exceeding Claude's context window or when summarizing multiple related documents together. Regardless, this meta-summarization technique often captures additional important details in the final summary that were missed in the earlier single-summary approach.
### Use summary indexed documents to explore a large collection of documents
Searching a collection of documents with an LLM usually involves retrieval-augmented generation (RAG). However, in scenarios involving large documents or when precise information retrieval is crucial, a basic RAG approach may be insufficient. Summary indexed documents is an advanced RAG approach that provides a more efficient way of ranking documents for retrieval, using less context than traditional RAG methods. In this approach, you first use Claude to generate a concise summary for each document in your corpus, and then use Claude to rank the relevance of each summary to the query being asked. For further details on this approach, including a code-based example, check out the summary indexed documents section in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide).
### Fine-tune Claude to learn from your dataset
Another advanced technique to improve Claude's ability to generate summaries is fine-tuning. Fine-tuning involves training Claude on a custom dataset that specifically aligns with your legal summarization needs, ensuring that Claude adapts to your use case. Here’s an overview on how to perform fine-tuning:
1. **Identify errors:** Start by collecting instances where Claude’s summaries fall short - this could include missing critical legal details, misunderstanding context, or using inappropriate legal terminology.
2. **Curate a dataset:** Once you've identified these issues, compile a dataset of these problematic examples. This dataset should include the original legal documents alongside your corrected summaries, ensuring that Claude learns the desired behavior.
3. **Perform fine-tuning:** Fine-tuning involves retraining the model on your curated dataset to adjust its weights and parameters. This retraining helps Claude better understand the specific requirements of your legal domain, improving its ability to summarize documents according to your standards.
4. **Iterative improvement:** Fine-tuning is not a one-time process. As Claude continues to generate summaries, you can iteratively add new examples where it has underperformed, further refining its capabilities. Over time, this continuous feedback loop will result in a model that is highly specialized for your legal summarization tasks.
<Tip>Fine-tuning is currently only available via Amazon Bedrock. Additional details are available in the [AWS launch blog](https://aws.amazon.com/blogs/machine-learning/fine-tune-anthropics-claude-3-haiku-in-amazon-bedrock-to-boost-model-accuracy-and-quality/).</Tip>
<CardGroup cols={2}>
<Card title="Summarization cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-summarization-guide">
View a fully implemented code-based example of how to use Claude to summarize contracts.
</Card>
<Card title="Citations cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
Explore the Citations cookbook recipe for guidance on how to ensure accuracy and explainability of information.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-legal-summarization-1b978423c3.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fuse-case-guides%2Flegal-summarization)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Use cases
# Legal summarization
Copy page
This guide walks through how to leverage Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
Copy page
> Visit the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide) to see an example legal summarization implementation using Claude.
## Before building with Claude
### Decide whether to use Claude for legal summarization
Here are some key indicators that you should employ an LLM such as Claude to summarize legal documents:
### You want to review a high volume of documents efficiently and affordably
Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks like due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
### You require automated extraction of key metadata
Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It's especially useful for contract management, compliance checks, or creating searchable databases of legal information.
### You want to generate clear, concise, and standardized summaries
Claude can generate structured summaries that follow predetermined formats, making it easier for legal professionals to quickly grasp the key points of various documents. These standardized summaries can improve readability, facilitate comparison between documents, and enhance overall comprehension, especially when dealing with complex legal language or technical jargon.
### You need precise citations for your summaries
When creating legal summaries, proper attribution and citation are crucial to ensure credibility and compliance with legal standards. Claude can be prompted to include accurate citations for all referenced legal points, making it easier for legal professionals to review and verify the summarized information.
### You want to streamline and expedite your legal research process
Claude can assist in legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
### Determine the details you want the summarization to extract
There is no single correct summary for any given document. Without clear direction, it can be difficult for Claude to determine which details to include. To achieve optimal results, identify the specific information you want to include in the summary.
For instance, when summarizing a sublease agreement, you might want to extract the following key points:
```python
details_to_extract = [
"Parties involved (sublessor, sublessee, and original lessor)",
"Property details (address, description, and permitted use)",
"Term and rent (start date, end date, monthly rent, and security deposit)",
"Responsibilities (utilities, maintenance, and repairs)",
"Consent and notices (landlord's consent, and notice requirements)",
"Special provisions (furniture, parking, and subletting restrictions)",
]
```
### Establish success criteria
Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you may want to consider when assessing how well Claude performs legal summarization.
### Factual correctness
The summary should accurately represent the facts, legal concepts, and key points in the document.
### Legal precision
Terminology and references to statutes, case law, or regulations must be correct and aligned with legal standards.
### Conciseness
The summary should condense the legal document to its essential points without losing important details.
### Consistency
If summarizing multiple documents, the LLM should maintain a consistent structure and approach to each summary.
### Readability
The text should be clear and easy to understand. If the audience is not legal experts, the summarization should not include legal jargon that could confuse the audience.
### Bias and fairness
The summary should present an unbiased and fair depiction of the legal arguments and positions.
See the guide on [establishing success criteria](/docs/en/test-and-evaluate/develop-tests) for more information.
------------------------------------------------------------------------
## How to summarize legal documents using Claude
### Select the right Claude model
Model accuracy is extremely important when summarizing legal documents. Claude Opus 5 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents is large such that costs start to become a concern, you can also try using a smaller model such as Claude Haiku 4.5.
To help estimate these costs, the following is a comparison of the cost to summarize 1,000 sublease agreements using Opus and Haiku models:
- **Content size**
- Number of agreements: 1,000
- Characters per agreement: 300,000
- Total characters: 300M
- **Estimated tokens**
- Input tokens: 86M (assuming 1 token per 3.5 characters)
- Output tokens per summary: 350
- Total output tokens: 350,000
- **Claude Opus 5 estimated cost**
- Input token cost: 86 MTok \* \$5.00/MTok = \$430.00 USD
- Output token cost: 0.35 MTok \* \$25.00/MTok = \$8.75 USD
- Total cost: \$430.00 + \$8.75 = \$438.75 USD
- **Claude Opus 4.8 estimated cost**
- Input token cost: 86 MTok \* \$5.00/MTok = \$430.00 USD
- Output token cost: 0.35 MTok \* \$25.00/MTok = \$8.75 USD
- Total cost: \$430.00 + \$8.75 = \$438.75 USD
- **Claude Haiku 4.5 estimated cost**
- Input token cost: 86 MTok \* \$1.00/MTok = \$86.00 USD
- Output token cost: 0.35 MTok \* \$5.00/MTok = \$1.75 USD
- Total cost: \$86.00 + \$1.75 = \$87.75 USD
Actual costs may differ from these estimates. These estimates are based on the example highlighted in the [Build a strong prompt](#build-a-strong-prompt) section.
### Transform documents into a format that Claude can process
Before you begin summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it's ready to be processed by Claude.
Here is a demonstration of this process on a sample PDF:
```python
from io import BytesIO
import re
import pypdf
import requests
def get_llm_text(pdf_file):
reader = pypdf.PdfReader(pdf_file)
text = "\n".join([page.extract_text() for page in reader.pages])
# Remove page numbers
text = re.sub(r"\n\s*\d+\s*\n", "\n", text)
# Remove extra whitespace
text = re.sub(r"\s+", " ", text)
return text
# Create the full URL from the GitHub repository
url = "https://raw.githubusercontent.com/anthropics/claude-cookbooks/main/capabilities/summarization/data/Sample Sublease Agreement.pdf"
url = url.replace(" ", "%20")
# Download the PDF file into memory
response = requests.get(url)
# Load the PDF from memory
pdf_file = BytesIO(response.content)
document_text = get_llm_text(pdf_file)
print(document_text[:50000])
```
In this example, you first download a PDF of a sample sublease agreement used in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).
The example uses the pypdf library to extract the contents of the PDF and convert it to text. The text data is then cleaned by removing page numbers and extra whitespace.
### Build a strong prompt
Claude can adapt to various summarization styles. You can change the details of the prompt to guide Claude to be more or less verbose, include more or less technical terminology, or provide a higher- or lower-level summary of the context at hand.
Here’s an example of how to create a prompt that ensures the generated summaries follow a consistent structure when analyzing sublease agreements:
Python
```python
# Initialize the Anthropic client
client = anthropic.Anthropic()
def summarize_document(
text, details_to_extract, model="claude-opus-5-5", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Prompt the model to summarize the sublease agreement
prompt = f"""Summarize the following sublease agreement. Focus on these key aspects:
{details_to_extract_str}
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
Sublease agreement text:
{text}
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal analyst specializing in real estate law, known for highly accurate and detailed summaries of sublease agreements.",
messages=[
{"role": "user", "content": prompt},
],
)
return next(block.text for block in response.content if block.type == "text")
sublease_summary = summarize_document(document_text, details_to_extract)
print(sublease_summary)
```
This code implements a `summarize_document` function that uses Claude to summarize the contents of a sublease agreement. The function accepts a text string and a list of details to extract as inputs. In this example, the code calls the function with the `document_text` and `details_to_extract` variables that were defined in the previous code snippets.
Within the function, a prompt is generated for Claude, including the document to be summarized, the details to extract, and specific instructions for summarizing the document. The prompt instructs Claude to respond with a summary of each detail to extract nested within XML headers.
Because the code outputs each section of the summary within tags, each section can easily be parsed out as a post-processing step. This approach enables structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
### Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](/docs/en/test-and-evaluate/develop-tests#build-evaluations) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you may want to include within your empirical evaluation:
### ROUGE scores
This measures the overlap between the generated summary and an expert-created reference summary. This metric primarily focuses on recall and is useful for evaluating content coverage.
### BLEU scores
Although originally developed for machine translation, this metric can be adapted for summarization tasks. BLEU scores measure the precision of n-gram matches between the generated summary and reference summaries. A higher score indicates that the generated summary contains similar phrases and terminology to the reference summary.
### Contextual embedding similarity
This metric involves creating vector representations (embeddings) of both the generated and reference summaries. The similarity between these embeddings is then calculated, often using cosine similarity. Higher similarity scores indicate that the generated summary captures the semantic meaning and context of the reference summary, even if the exact wording differs.
### LLM-based grading
This method involves using an LLM such as Claude to evaluate the quality of generated summaries against a scoring rubric. The rubric can be tailored to your specific needs, assessing key factors such as accuracy, completeness, and coherence. For implementation guidance, see [Tips for LLM-based grading](/docs/en/test-and-evaluate/develop-tests#tips-for-llm-based-grading).
### Human evaluation
In addition to creating the reference summaries, legal experts can also evaluate the quality of the generated summaries. Although this is expensive and time-consuming at scale, this is often done on a few summaries as a validation check before deploying to production.
### Deploy your prompt
Here are some additional considerations to keep in mind as you deploy your solution to production.
1. **Ensure no liability:** Understand the legal implications of errors in the summaries, which could lead to legal liability for your organization or clients. Provide disclaimers or legal notices clarifying that the summaries are generated by AI and should be reviewed by legal professionals.
2. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real world, documents may come in a variety of formats (such as PDFs, Word documents, and text files). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
3. **Parallelize API calls to Claude:** Long documents with a large number of tokens may require up to a minute for Claude to generate a summary. For large document collections, you may want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](/docs/en/api/rate-limits#rate-limits) to determine the maximum amount of API calls that can be performed in parallel.
------------------------------------------------------------------------
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Perform meta-summarization to summarize long documents
Legal summarization often involves handling long documents or many related documents at once, such that you surpass Claude’s context window. You can use a chunking method known as meta-summarization to handle this use case. This technique involves breaking down documents into smaller, manageable chunks and then processing each chunk separately. You can then combine the summaries of each chunk to create a meta-summary of the entire document.
Here's an example of how to perform meta-summarization:
Python
```python
# Initialize the Anthropic client
client = anthropic.Anthropic()
def chunk_text(text, chunk_size=20000):
return [text[i : i + chunk_size] for i in range(0, len(text), chunk_size)]
def summarize_long_document(
text, details_to_extract, model="claude-opus-5-5", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Iterate over chunks and summarize each one
chunk_summaries = [
summarize_document(
chunk, details_to_extract, model=model, max_tokens=max_tokens
)
for chunk in chunk_text(text)
]
final_summary_prompt = f"""
You are looking at the chunked summaries of multiple documents that are all related.
Combine the following summaries of the document from different truthful sources into a coherent overall summary:
<chunked_summaries>
{"".join(chunk_summaries)}
</chunked_summaries>
Focus on these key aspects:
{details_to_extract_str}
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal expert that summarizes notes on one document.",
messages=[
{"role": "user", "content": final_summary_prompt},
],
)
return next(block.text for block in response.content if block.type == "text")
long_summary = summarize_long_document(document_text, details_to_extract)
print(long_summary)
```
The `summarize_long_document` function builds upon the earlier `summarize_document` function by splitting the document into smaller chunks and summarizing each chunk individually.
The code achieves this by applying the `summarize_document` function to each chunk of 20,000 characters within the original document. The individual summaries are then combined, and a final summary is created from these chunk summaries.
Note that the `summarize_long_document` function isn't strictly necessary for the example PDF, as the entire document fits within Claude's context window. However, it becomes essential for documents exceeding Claude's context window or when summarizing multiple related documents together. Regardless, this meta-summarization technique often captures additional important details in the final summary that were missed in the earlier single-summary approach.
### Use summary indexed documents to explore a large collection of documents
Searching a collection of documents with an LLM usually involves retrieval-augmented generation (RAG). However, in scenarios involving large documents or when precise information retrieval is crucial, a basic RAG approach may be insufficient. Summary indexed documents is an advanced RAG approach that provides a more efficient way of ranking documents for retrieval, using less context than traditional RAG methods. In this approach, you first use Claude to generate a concise summary for each document in your corpus, and then use Claude to rank the relevance of each summary to the query being asked. For further details on this approach, including a code-based example, check out the summary indexed documents section in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide).
### Fine-tune Claude to learn from your dataset
Another advanced technique to improve Claude's ability to generate summaries is fine-tuning. Fine-tuning involves training Claude on a custom dataset that specifically aligns with your legal summarization needs, ensuring that Claude adapts to your use case. Here’s an overview on how to perform fine-tuning:
1. **Identify errors:** Start by collecting instances where Claude’s summaries fall short - this could include missing critical legal details, misunderstanding context, or using inappropriate legal terminology.
2. **Curate a dataset:** Once you've identified these issues, compile a dataset of these problematic examples. This dataset should include the original legal documents alongside your corrected summaries, ensuring that Claude learns the desired behavior.
3. **Perform fine-tuning:** Fine-tuning involves retraining the model on your curated dataset to adjust its weights and parameters. This retraining helps Claude better adapt to the specific requirements of your legal domain, improving its ability to summarize documents according to your standards.
4. **Iterative improvement:** Fine-tuning is not a one-time process. As Claude continues to generate summaries, you can iteratively add new examples where it has underperformed, further refining its capabilities. Over time, this continuous feedback loop will result in a model that is highly specialized for your legal summarization tasks.
Fine-tuning is currently only available through Amazon Bedrock. Additional details are available in the [AWS launch blog](https://aws.amazon.com/blogs/machine-learning/fine-tune-anthropics-claude-3-haiku-in-amazon-bedrock-to-boost-model-accuracy-and-quality/).
[Summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide)
View a fully implemented code-based example of how to use Claude to summarize contracts.
[Citations cookbook](https://platform.claude.com/cookbook/misc-using-citations)
Explore the Citations cookbook recipe for guidance on how to ensure accuracy and explainability of information.
---
## About/about-claude-use-case-guides-overview-43239e353a.md
# Guides to common use cases
---
Claude is designed to excel in a variety of tasks. Explore these in-depth production guides to learn how to build common use cases with Claude.
<CardGroup cols={2}>
<Card title="Ticket routing" icon="headset" href="/docs/en/about-claude/use-case-guides/ticket-routing">
Best practices for using Claude to classify and route customer support tickets at scale.
</Card>
<Card title="Customer support agent" icon="robot" href="/docs/en/about-claude/use-case-guides/customer-support-chat">
Build intelligent, context-aware chatbots with Claude to enhance customer support interactions.
</Card>
<Card title="Content moderation" icon="verified" href="/docs/en/about-claude/use-case-guides/content-moderation">
Techniques and best practices for using Claude to perform content filtering and general content moderation.
</Card>
<Card title="Legal summarization" icon="book" href="/docs/en/about-claude/use-case-guides/legal-summarization">
Summarize legal documents using Claude to extract key information and expedite research.
</Card>
</CardGroup>
---
## About/about-claude-use-case-guides-overview-971d8d1b66.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fuse-case-guides%2Foverview)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
Best practicesUse cases
# Guides to common use cases
Copy page
Explore production guides for building common Claude use cases: ticket routing, customer support agents, content moderation, legal summarization, and commerce agents.
Copy page
Claude is designed to excel in a variety of tasks. Explore these in-depth production guides to learn how to build common use cases with Claude.
[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)
Best practices for using Claude to classify and route customer support tickets at scale.
[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)
Build intelligent, context-aware chatbots with Claude to enhance customer support interactions.
[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)
Techniques and best practices for using Claude to perform content filtering and general content moderation.
[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)
Summarize legal documents using Claude to extract key information and expedite research.
[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Build shopping and merchant agents from an open-source blueprint that runs on the Messages API, the Claude Agent SDK, and Claude Managed Agents.
## Choosing a build path
The three paths for building with Claude differ in how much control you keep and how much of the implementation you offload to Anthropic. The [Messages API](/docs/en/build-with-claude/working-with-messages) gives you the most control: you write the agent loop and run your own tools and infrastructure. The [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) sits in between, providing the agent loop and tool execution in a process you operate. With [Claude Managed Agents](/docs/en/managed-agents/overview), you offload the most: Anthropic hosts the agent loop, tool execution, and runtime for you.
---
## About/about-claude-use-case-guides-ticket-routing-6f7b0bee2e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fabout-claude%2Fuse-case-guides%2Fticket-routing)
SearchCtrlK
Use cases
[Overview](/docs/en/about-claude/use-case-guides/overview)[Ticket routing](/docs/en/about-claude/use-case-guides/ticket-routing)[Customer support agent](/docs/en/about-claude/use-case-guides/customer-support-chat)[Content moderation](/docs/en/about-claude/use-case-guides/content-moderation)[Legal summarization](/docs/en/about-claude/use-case-guides/legal-summarization)[Commerce agent](/docs/en/about-claude/use-case-guides/commerce-agents)
Prompt engineering
[Overview](/docs/en/build-with-claude/prompt-engineering/overview)[Prompting best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)[Prompting Claude Fable 5.1](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1)[Prompting Claude Fable 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5)[Prompting Claude Opus 5.5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)[Prompting Claude Opus 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)[Prompting Claude Opus 4.8](/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-4-8)[Prompting Claude Sonnet 5](/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5)
Test and evaluate
[Define success and build evaluations](/docs/en/test-and-evaluate/develop-tests)[Reducing latency](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency)
Strengthen guardrails
[Reduce hallucinations](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations)[Increase output consistency](/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency)[Mitigate jailbreaks](/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)[Reduce prompt leak](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-prompt-leak)
Reference
[Glossary](/docs/en/about-claude/glossary)[Additional resources](/docs/en/about-claude/additional-resources)
[Console](/)
[Best practices](/docs/en/about-claude/use-case-guides/overview)Use cases
# Ticket routing
Copy page
This guide walks through how to harness Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
Copy page
## Prerequisites
- A Claude API key and the Python SDK installed
- Access to, and familiarity with, your existing support ticketing system
- A sample set of historical support tickets for testing
## Define whether to use Claude for ticket routing
Here are some key indicators that you should use an LLM like Claude instead of traditional ML approaches for your classification task:
### You have limited labeled training data available
Traditional ML processes require massive labeled datasets. Claude's pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.
### Your classification categories are likely to change or evolve over time
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes in class definitions or new classes without extensive relabeling of training data.
### You need to handle complex, unstructured text inputs
Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude's advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.
### Your classification rules are based on semantic understanding
Traditional ML approaches often rely on bag-of-words models or simple pattern matching. Claude excels at understanding and applying underlying rules when classes are defined by conditions rather than examples.
### You require interpretable reasoning for classification decisions
Many traditional ML models provide little insight into their decision-making process. Claude can provide human-readable explanations for its classification decisions, building trust in the automation system and facilitating easy adaptation if needed.
### You want to handle edge cases and ambiguous tickets more effectively
Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude's natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.
### You need multilingual support without maintaining separate models
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude's multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.
------------------------------------------------------------------------
## Build and deploy your LLM support workflow
### Understand your current support approach
Before you automate, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.
Consider questions like:
- What criteria are used to determine what SLA/service offering is applied?
- Is ticket routing used to determine which tier of support or product specialist a ticket goes to?
- Are there any automated rules or workflows already in place? In what cases do they fail?
- How are edge cases or ambiguous tickets handled?
- How does the team prioritize tickets?
The more you know about how humans handle certain cases, the better you can work with Claude to do the task.
### Define user intent categories
A well-defined list of user intent categories is crucial for accurate support ticket classification with Claude. Claude’s ability to route tickets effectively within your system is directly proportional to how well-defined your system’s categories are.
Here are some example user intent categories and subcategories.
### Technical issue
- Hardware problem
- Software bug
- Compatibility issue
- Performance problem
### Account management
- Password reset
- Account access issues
- Billing inquiries
- Subscription changes
### Product information
- Feature inquiries
- Product compatibility questions
- Pricing information
- Availability inquiries
### User guidance
- How-to questions
- Feature usage assistance
- Best practices advice
- Troubleshooting guidance
### Feedback
- Bug reports
- Feature requests
- General feedback or suggestions
- Complaints
### Order-related
- Order status inquiries
- Shipping information
- Returns and exchanges
- Order modifications
### Service request
- Installation assistance
- Upgrade requests
- Maintenance scheduling
- Service cancellation
### Security concerns
- Data privacy inquiries
- Suspicious activity reports
- Security feature assistance
### Compliance and legal
- Regulatory compliance questions
- Terms of service inquiries
- Legal documentation requests
### Emergency support
- Critical system failures
- Urgent security issues
- Time-sensitive problems
### Training and education
- Product training requests
- Documentation inquiries
- Webinar or workshop information
### Integration and API
- Integration assistance
- API usage questions
- Third-party compatibility inquiries
In addition to intent, ticket routing and prioritization may also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
### Establish success criteria
Work with your support team to [define clear success criteria](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks, thresholds, and goals.
Here are some standard criteria and benchmarks when using LLMs for support ticket routing:
### Classification consistency
This metric assesses how consistently Claude classifies similar tickets over time. It's crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95% or higher.
### Adaptation speed
This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (for example, \>90%) on these new categories. Aim for adaptation within 50–100 sample tickets.
### Multilingual handling
This assesses Claude's ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5–10% drop in accuracy for non-primary languages.
### Edge case handling
This evaluates Claude's performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80% accuracy on these challenging inputs.
### Bias mitigation
This measures Claude's fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2–3%) across all customer groups.
### Prompt efficiency
In situations where minimizing token count is crucial, this criteria assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for 90%+ accuracy with just the ticket title and a brief description.
### Explainability score
This evaluates the quality and relevance of Claude's explanations for its routing decisions. Human raters can score explanations on a scale (for example, 1–5), with the goal of achieving an average score of 4 or higher.
Here are some common success criteria that may be useful regardless of whether an LLM is used:
### Routing accuracy
Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90–95% accuracy, though this can vary based on the complexity of the support structure.
### Time-to-assignment
This metric tracks how quickly tickets are assigned after being submitted. Faster assignment times generally lead to quicker resolutions and improved customer satisfaction. Best-in-class systems often achieve average assignment times of under 5 minutes, with many aiming for near-instantaneous routing (which is possible with LLM implementations).
### Rerouting rate
The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10%, with top-performing systems achieving rates as low as 5% or less.
### First-contact resolution rate
This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70–75%, with top performers achieving rates of 80% or higher.
### Average handling time
Average handling time measures how long it takes to resolve a ticket from start to finish. Efficient routing can significantly reduce this time. Benchmarks vary widely by industry and complexity, but many organizations aim to keep average handling time under 24 hours for non-critical issues.
### Customer satisfaction scores
Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90% or higher, with top performers often achieving 95%+ satisfaction rates.
### Escalation rate
This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20%, with best-in-class systems achieving rates of 10% or less.
### Agent productivity
This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10–20% improvement after implementing a new routing system.
### Self-service deflection rate
This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20–30%, with top performers achieving rates of 40% or higher.
### Cost per ticket
This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. While benchmarks vary widely, many organizations aim to reduce cost per ticket by 10–15% after implementing an improved routing system.
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
Many customers have found `claude-haiku-4-5-20251001` an ideal model for ticket routing, as it is the fastest and most cost-effective model in the Claude 4 family while still delivering excellent results. If your classification problem requires deep subject matter expertise or a large volume of intent categories, or complex reasoning, you may opt for the [larger Sonnet model](/docs/en/models/overview).
### Build a strong prompt
Ticket routing is a type of classification task. Claude analyzes the content of a support ticket and classifies it into predefined categories based on the issue type, urgency, required expertise, or other relevant factors.
Write a ticket classification prompt. The initial prompt should contain the contents of the user request and return both the reasoning and the intent.
Try the [metaprompt recipe from the Claude Cookbook](https://colab.research.google.com/github/anthropics/claude-cookbooks/blob/main/misc/metaprompt.ipynb) to have Claude write a first draft for you.
Here's an example ticket routing classification prompt:
```python
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system. Your task is to analyze customer support requests and output the appropriate classification intent for each request, along with your reasoning.
Here is the customer support request you need to classify:
<request>{ticket_contents}</request>
Please carefully analyze the above request to determine the customer's core intent and needs. Consider what the customer is asking for has concerns about.
First, write out your reasoning and analysis of how to classify this request inside <reasoning> tags.
Then, output the appropriate classification label for the request inside a <intent> tag. The valid intents are:
<intents>
<intent>Support, Feedback, Complaint</intent>
<intent>Order Tracking</intent>
<intent>Refund/Exchange</intent>
</intents>
A request may have ONLY ONE applicable intent. Only include the intent that is most applicable to the request.
As an example, consider the following request:
<request>Hello! I had high-speed fiber internet installed on Saturday and my installer, Kevin, was absolutely fantastic! Where can I send my positive review? Thanks for your help!</request>
Here is an example of how your output should be formatted (for the above example request):
<reasoning>The user seeks information in order to leave positive feedback.</reasoning>
<intent>Support, Feedback, Complaint</intent>
Here are a few more examples:
<examples>
<example 2>
Example 2 Input:
<request>I wanted to write and personally thank you for the compassion you showed towards my family during my father's funeral this past weekend. Your staff was so considerate and helpful throughout this whole process; it really took a load off our shoulders. The visitation brochures were beautiful. We'll never forget the kindness you showed us and we are so appreciative of how smoothly the proceedings went. Thank you, again, Amarantha Hill on behalf of the Hill Family.</request>
Example 2 Output:
<reasoning>User leaves a positive review of their experience.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 2>
<example 3>
...
</example 8>
<example 9>
Example 9 Input:
<request>Your website keeps sending ad-popups that block the entire screen. It took me twenty minutes just to finally find the phone number to call and complain. How can I possibly access my account information with all of these popups? Can you access my account for me, since your website is broken? I need to know what the address is on file.</request>
Example 9 Output:
<reasoning>The user requests help accessing their web account information.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 9>
Remember to always include your classification reasoning before your actual intent output. The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
```
Here are the key components of this prompt:
- The prompt template is a Python f-string, allowing the `ticket_contents` to be inserted into the `<request>` tags.
- The prompt gives Claude a clearly defined role as a classification system that carefully analyzes the ticket content to determine the customer's core intent and needs.
- The prompt instructs Claude on proper output formatting, in this case to provide its reasoning and analysis inside `<reasoning>` tags, followed by the appropriate classification label inside `<intent>` tags.
- The prompt specifies the valid intent categories: "Support, Feedback, Complaint", "Order Tracking", and "Refund/Exchange".
- The prompt includes a few examples (a.k.a. few-shot prompting) to illustrate how the output should be formatted, which improves accuracy and consistency.
Having Claude split its response into separate XML tag sections lets you use regular expressions to extract the reasoning and intent from the output independently. This lets you create targeted next steps in the ticket routing workflow, such as using only the intent to decide which person to route the ticket to.
### Deploy your prompt
It’s hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests).
Build the deployment structure. Start by defining the method signature for wrapping the call to Claude. Extend the method you began writing earlier, which takes `ticket_contents` as input, so that it now returns a tuple of `reasoning` and `intent` as output. If you have an existing automation using traditional ML, you'll want to follow that method signature instead.
Python
```python
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
... The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
# Send the prompt to the API to classify the support request.
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
messages=[{"role": "user", "content": classification_prompt}],
stream=False,
)
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
return reasoning, intent
```
This code:
- Creates a client instance using your API key.
- Defines a `classify_support_request` function that takes a `ticket_contents` string.
- Sends the `ticket_contents` to Claude for classification using the `classification_prompt`.
- Returns the model's `reasoning` and `intent` extracted from the response.
Because the entire reasoning and intent text must be generated before parsing, the example sets `stream=False` (the default).
------------------------------------------------------------------------
## Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate performance based on the success criteria and thresholds you established earlier.
To run your evaluation, you need test cases to run it on. The rest of this guide assumes you have already [developed your test cases](/docs/en/test-and-evaluate/develop-tests).
### Build an evaluation function
The example evaluation for this guide measures Claude’s performance along three key metrics:
- Accuracy
- Cost per classification
You may need to assess Claude on other axes depending on what factors that are important to you.
To assess this, first modify the script to add a function that compares the predicted intent with the actual intent and calculates the percentage of correct predictions. Then add cost calculation and time measurement functionality.
Python
```python
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(request, actual_intent):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
...The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
messages=[{"role": "user", "content": classification_prompt}],
)
usage = message.usage # Get the usage statistics for the API call for how many input and output tokens were used.
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
# Check if the model's prediction is correct.
correct = actual_intent.strip() == intent.strip()
# Return the reasoning, intent, correct, and usage.
return reasoning, intent, correct, usage
```
Here is a breakdown of the edits:
- The `classify_support_request` method now takes the `actual_intent` from the test cases and compares it against Claude’s intent classification to assess whether they match.
- The method extracts usage statistics for the API call to calculate cost based on input and output tokens used.
### Run your evaluation
A proper evaluation requires clear thresholds and benchmarks to determine what is a good result. The preceding script returns the runtime values for accuracy, response time, and cost per classification, but you still need clearly established thresholds. For example:
- **Accuracy:** 95% (out of 100 tests)
- **Cost per classification:** 50% reduction on average (across 100 tests) from current routing method
Having these thresholds allows you to quickly and easily tell at scale, and with impartial empiricism, what method is best for you and what changes might need to be made to better fit your requirements.
------------------------------------------------------------------------
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
### Use a taxonomic hierarchy for cases with 20+ intent categories
As the number of classes grows, the number of examples required also expands, potentially making the prompt unwieldy. As an alternative, you can consider implementing a hierarchical classification system using a mixture of classifiers.
1. Organize your intents in a taxonomic tree structure.
2. Create a series of classifiers at every level of the tree, enabling a cascading routing approach.
For example, you might have a top-level classifier that broadly categorizes tickets into "Technical Issues," "Billing Questions," and "General Inquiries." Each of these categories can then have its own sub-classifier to further refine the classification.
- **Pros - greater nuance and accuracy:** You can create different prompts for each parent path, allowing for more targeted and context-specific classification. This can lead to improved accuracy and more nuanced handling of customer requests.
- **Cons - increased latency:** Be advised that multiple classifiers can lead to increased latency, and Anthropic recommends implementing this approach with the fastest model, Haiku.
### Use vector databases and similarity search retrieval to handle highly variable tickets
Despite providing examples being the most effective way to improve performance, if support requests are highly variable, it can be hard to include enough examples in a single prompt.
In this scenario, you could employ a vector database to do similarity searches from a dataset of examples and retrieve the most relevant examples for a given query.
This approach, outlined in detail in the [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide), has been shown to improve performance from 71% accuracy to 93% accuracy.
### Account specifically for expected edge cases
Here are some scenarios where Claude may misclassify tickets (there may be others that are unique to your situation). In these scenarios, consider providing explicit instructions or examples in the prompt of how Claude should handle the edge case:
### Customers make implicit requests
Customers often express needs indirectly. For example, "I've been waiting for my package for over two weeks now" may be an indirect request for order status.
- **Solution:** Provide Claude with some real customer examples of these kinds of requests, along with what the underlying intent is. You can get even better results if you include a classification rationale for particularly nuanced ticket intents, so that Claude can better generalize the logic to other tickets.
### Claude prioritizes emotion over intent
When customers express dissatisfaction, Claude may prioritize addressing the emotion over solving the underlying problem.
- **Solution:** Provide Claude with directions on when to prioritize customer sentiment or not. It can be something as simple as “Ignore all customer emotions. Focus only on analyzing the intent of the customer’s request and what information the customer might be asking for.”
### Multiple issues cause issue prioritization confusion
When customers present multiple issues in a single interaction, Claude may have difficulty identifying the primary concern.
- **Solution:** Clarify the prioritization of intents so that Claude can better rank the extracted intents and identify the primary concern.
------------------------------------------------------------------------
## Integrate Claude into your greater support workflow
Proper integration requires that you make some decisions regarding how your Claude-based ticket routing script fits into the architecture of your greater ticket routing system. There are two ways you could do this:
- **Push-based:** The support ticket system you’re using (for example, Zendesk) triggers your code by sending a webhook event to your routing service, which then classifies the intent and routes it.
- This approach is more web-scalable, but needs you to expose a public endpoint.
- **Pull-based:** Your code pulls for the latest tickets based on a given schedule and routes them at pull time.
- This approach is easier to implement but might make unnecessary calls to the support ticket system when the pull frequency is too high or might be overly slow when the pull frequency is too low.
For either of these approaches, you need to wrap your script in a service. The choice of approach depends on what APIs your support ticketing system provides.
------------------------------------------------------------------------
[Classification cookbook](https://platform.claude.com/cookbook/capabilities-classification-guide)
Visit the classification cookbook for more example code and detailed eval guidance.
[Claude Console](/dashboard)
Begin building and evaluating your workflow on the Claude Console.
---
## About/about-claude-use-case-guides-ticket-routing-95526bdf0d.md
# Ticket routing
This guide walks through how to harness Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
---
## Define whether to use Claude for ticket routing
Here are some key indicators that you should use an LLM like Claude instead of traditional ML approaches for your classification task:
<section title="You have limited labeled training data available">
Traditional ML processes require massive labeled datasets. Claude's pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.
</section>
<section title="Your classification categories are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes in class definitions or new classes without extensive relabeling of training data.
</section>
<section title="You need to handle complex, unstructured text inputs">
Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude's advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.
</section>
<section title="Your classification rules are based on semantic understanding">
Traditional ML approaches often rely on bag-of-words models or simple pattern matching. Claude excels at understanding and applying underlying rules when classes are defined by conditions rather than examples.
</section>
<section title="You require interpretable reasoning for classification decisions">
Many traditional ML models provide little insight into their decision-making process. Claude can provide human-readable explanations for its classification decisions, building trust in the automation system and facilitating easy adaptation if needed.
</section>
<section title="You want to handle edge cases and ambiguous tickets more effectively">
Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude's natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.
</section>
<section title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude's multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.
</section>
***
## Build and deploy your LLM support workflow
### Understand your current support approach
Before diving into automation, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.
Consider questions like:
* What criteria are used to determine what SLA/service offering is applied?
* Is ticket routing used to determine which tier of support or product specialist a ticket goes to?
* Are there any automated rules or workflows already in place? In what cases do they fail?
* How are edge cases or ambiguous tickets handled?
* How does the team prioritize tickets?
The more you know about how humans handle certain cases, the better you can work with Claude to do the task.
### Define user intent categories
A well-defined list of user intent categories is crucial for accurate support ticket classification with Claude. Claude’s ability to route tickets effectively within your system is directly proportional to how well-defined your system’s categories are.
Here are some example user intent categories and subcategories.
<section title="Technical issue">
* Hardware problem
* Software bug
* Compatibility issue
* Performance problem
</section>
<section title="Account management">
* Password reset
* Account access issues
* Billing inquiries
* Subscription changes
</section>
<section title="Product information">
* Feature inquiries
* Product compatibility questions
* Pricing information
* Availability inquiries
</section>
<section title="User guidance">
* How-to questions
* Feature usage assistance
* Best practices advice
* Troubleshooting guidance
</section>
<section title="Feedback">
* Bug reports
* Feature requests
* General feedback or suggestions
* Complaints
</section>
<section title="Order-related">
* Order status inquiries
* Shipping information
* Returns and exchanges
* Order modifications
</section>
<section title="Service request">
* Installation assistance
* Upgrade requests
* Maintenance scheduling
* Service cancellation
</section>
<section title="Security concerns">
* Data privacy inquiries
* Suspicious activity reports
* Security feature assistance
</section>
<section title="Compliance and legal">
* Regulatory compliance questions
* Terms of service inquiries
* Legal documentation requests
</section>
<section title="Emergency support">
* Critical system failures
* Urgent security issues
* Time-sensitive problems
</section>
<section title="Training and education">
* Product training requests
* Documentation inquiries
* Webinar or workshop information
</section>
<section title="Integration and API">
* Integration assistance
* API usage questions
* Third-party compatibility inquiries
</section>
In addition to intent, ticket routing and prioritization may also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
### Establish success criteria
Work with your support team to [define clear success criteria](/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks, thresholds, and goals.
Here are some standard criteria and benchmarks when using LLMs for support ticket routing:
<section title="Classification consistency">
This metric assesses how consistently Claude classifies similar tickets over time. It's crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95% or higher.
</section>
<section title="Adaptation speed">
This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (e.g., >90%) on these new categories. Aim for adaptation within 50-100 sample tickets.
</section>
<section title="Multilingual handling">
This assesses Claude's ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5-10% drop in accuracy for non-primary languages.
</section>
<section title="Edge case handling">
This evaluates Claude's performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80% accuracy on these challenging inputs.
</section>
<section title="Bias mitigation">
This measures Claude's fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2-3%) across all customer groups.
</section>
<section title="Prompt efficiency">
In situations where minimizing token count is crucial, this criteria assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for 90%+ accuracy with just the ticket title and a brief description.
</section>
<section title="Explainability score">
This evaluates the quality and relevance of Claude's explanations for its routing decisions. Human raters can score explanations on a scale (e.g., 1-5), with the goal of achieving an average score of 4 or higher.
</section>
Here are some common success criteria that may be useful regardless of whether an LLM is used:
<section title="Routing accuracy">
Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90-95% accuracy, though this can vary based on the complexity of the support structure.
</section>
<section title="Time-to-assignment">
This metric tracks how quickly tickets are assigned after being submitted. Faster assignment times generally lead to quicker resolutions and improved customer satisfaction. Best-in-class systems often achieve average assignment times of under 5 minutes, with many aiming for near-instantaneous routing (which is possible with LLM implementations).
</section>
<section title="Rerouting rate">
The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10%, with top-performing systems achieving rates as low as 5% or less.
</section>
<section title="First-contact resolution rate">
This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70-75%, with top performers achieving rates of 80% or higher.
</section>
<section title="Average handling time">
Average handling time measures how long it takes to resolve a ticket from start to finish. Efficient routing can significantly reduce this time. Benchmarks vary widely by industry and complexity, but many organizations aim to keep average handling time under 24 hours for non-critical issues.
</section>
<section title="Customer satisfaction scores">
Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90% or higher, with top performers often achieving 95%+ satisfaction rates.
</section>
<section title="Escalation rate">
This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20%, with best-in-class systems achieving rates of 10% or less.
</section>
<section title="Agent productivity">
This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10-20% improvement after implementing a new routing system.
</section>
<section title="Self-service deflection rate">
This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20-30%, with top performers achieving rates of 40% or higher.
</section>
<section title="Cost per ticket">
This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. While benchmarks vary widely, many organizations aim to reduce cost per ticket by 10-15% after implementing an improved routing system.
</section>
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
Many customers have found `claude-haiku-4-5-20251001` an ideal model for ticket routing, as it is the fastest and most cost-effective model in the Claude 4 family while still delivering excellent results. If your classification problem requires deep subject matter expertise or a large volume of intent categories complex reasoning, you may opt for the [larger Sonnet model](/docs/en/about-claude/models).
### Build a strong prompt
Ticket routing is a type of classification task. Claude analyzes the content of a support ticket and classifies it into predefined categories based on the issue type, urgency, required expertise, or other relevant factors.
Let’s write a ticket classification prompt. Our initial prompt should contain the contents of the user request and return both the reasoning and the intent.
<Tip>
Try the [prompt generator](/docs/en/prompt-generator) on the [Claude Console](/login) to have Claude write a first draft for you.
</Tip>
Here's an example ticket routing classification prompt:
```python nocheck
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system. Your task is to analyze customer support requests and output the appropriate classification intent for each request, along with your reasoning.
Here is the customer support request you need to classify:
<request>{ticket_contents}</request>
Please carefully analyze the above request to determine the customer's core intent and needs. Consider what the customer is asking for has concerns about.
First, write out your reasoning and analysis of how to classify this request inside <reasoning> tags.
Then, output the appropriate classification label for the request inside a <intent> tag. The valid intents are:
<intents>
<intent>Support, Feedback, Complaint</intent>
<intent>Order Tracking</intent>
<intent>Refund/Exchange</intent>
</intents>
A request may have ONLY ONE applicable intent. Only include the intent that is most applicable to the request.
As an example, consider the following request:
<request>Hello! I had high-speed fiber internet installed on Saturday and my installer, Kevin, was absolutely fantastic! Where can I send my positive review? Thanks for your help!</request>
Here is an example of how your output should be formatted (for the above example request):
<reasoning>The user seeks information in order to leave positive feedback.</reasoning>
<intent>Support, Feedback, Complaint</intent>
Here are a few more examples:
<examples>
<example 2>
Example 2 Input:
<request>I wanted to write and personally thank you for the compassion you showed towards my family during my father's funeral this past weekend. Your staff was so considerate and helpful throughout this whole process; it really took a load off our shoulders. The visitation brochures were beautiful. We'll never forget the kindness you showed us and we are so appreciative of how smoothly the proceedings went. Thank you, again, Amarantha Hill on behalf of the Hill Family.</request>
Example 2 Output:
<reasoning>User leaves a positive review of their experience.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 2>
<example 3>
...
</example 8>
<example 9>
Example 9 Input:
<request>Your website keeps sending ad-popups that block the entire screen. It took me twenty minutes just to finally find the phone number to call and complain. How can I possibly access my account information with all of these popups? Can you access my account for me, since your website is broken? I need to know what the address is on file.</request>
Example 9 Output:
<reasoning>The user requests help accessing their web account information.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 9>
Remember to always include your classification reasoning before your actual intent output. The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
```
Let's break down the key components of this prompt:
* We use Python f-strings to create the prompt template, allowing the `ticket_contents` to be inserted into the `<request>` tags.
* We give Claude a clearly defined role as a classification system that carefully analyzes the ticket content to determine the customer's core intent and needs.
* We instruct Claude on proper output formatting, in this case to provide its reasoning and analysis inside `<reasoning>` tags, followed by the appropriate classification label inside `<intent>` tags.
* We specify the valid intent categories: "Support, Feedback, Complaint", "Order Tracking", and "Refund/Exchange".
* We include a few examples (a.k.a. few-shot prompting) to illustrate how the output should be formatted, which improves accuracy and consistency.
The reason we want to have Claude split its response into various XML tag sections is so that we can use regular expressions to separately extract the reasoning and intent from the output. This allows us to create targeted next steps in the ticket routing workflow, such as using only the intent to decide which person to route the ticket to.
### Deploy your prompt
It’s hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](/docs/en/test-and-evaluate/develop-tests).
Let’s build the deployment structure. Start by defining the method signature for wrapping our call to Claude. We'll take the method we’ve already begun to write, which has `ticket_contents` as input, and now return a tuple of `reasoning` and `intent` as output. If you have an existing automation using traditional ML, you'll want to follow that method signature instead.
```python Python nocheck hidelines={1}
import anthropic
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
... The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
# Send the prompt to the API to classify the support request.
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
temperature=0,
messages=[{"role": "user", "content": classification_prompt}],
stream=False,
)
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
return reasoning, intent
```
This code:
* Creates a client instance using your API key.
* Defines a `classify_support_request` function that takes a `ticket_contents` string.
* Sends the `ticket_contents` to Claude for classification using the `classification_prompt`
* Returns the model's `reasoning` and `intent` extracted from the response.
Since we need to wait for the entire reasoning and intent text to be generated before parsing, we set `stream=False` (the default).
***
## Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate performance based on the success criteria and thresholds you established earlier.
To run your evaluation, you need test cases to run it on. The rest of this guide assumes you have already [developed your test cases](/docs/en/test-and-evaluate/develop-tests).
### Build an evaluation function
Our example evaluation for this guide measures Claude’s performance along three key metrics:
* Accuracy
* Cost per classification
You may need to assess Claude on other axes depending on what factors that are important to you.
To assess this, we first have to modify the script we wrote and add a function to compare the predicted intent with the actual intent and calculate the percentage of correct predictions. We also have to add in cost calculation and time measurement functionality.
```python Python nocheck hidelines={1}
import anthropic
import re
# Create an instance of the Claude API client
client = anthropic.Anthropic()
# Set the default model
DEFAULT_MODEL = "claude-haiku-4-5-20251001"
def classify_support_request(request, actual_intent):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system.
...
...The reasoning should be enclosed in <reasoning> tags and the intent in <intent> tags. Return only the reasoning and the intent.
"""
message = client.messages.create(
model=DEFAULT_MODEL,
max_tokens=500,
temperature=0,
messages=[{"role": "user", "content": classification_prompt}],
)
usage = message.usage # Get the usage statistics for the API call for how many input and output tokens were used.
reasoning_and_intent = message.content[0].text
# Use Python's regular expressions library to extract `reasoning`.
reasoning_match = re.search(
r"<reasoning>(.*?)</reasoning>", reasoning_and_intent, re.DOTALL
)
reasoning = reasoning_match.group(1).strip() if reasoning_match else ""
# Similarly, also extract the `intent`.
intent_match = re.search(r"<intent>(.*?)</intent>", reasoning_and_intent, re.DOTALL)
intent = intent_match.group(1).strip() if intent_match else ""
# Check if the model's prediction is correct.
correct = actual_intent.strip() == intent.strip()
# Return the reasoning, intent, correct, and usage.
return reasoning, intent, correct, usage
```
Let’s break down the edits we’ve made:
* We added the `actual_intent` from our test cases into the `classify_support_request` method and set up a comparison to assess whether Claude’s intent classification matches our golden intent classification.
* We extracted usage statistics for the API call to calculate cost based on input and output tokens used
### Run your evaluation
A proper evaluation requires clear thresholds and benchmarks to determine what is a good result. The script above gives us the runtime values for accuracy, response time, and cost per classification, but we still would need clearly established thresholds. For example:
* **Accuracy:** 95% (out of 100 tests)
* **Cost per classification:** 50% reduction on average (across 100 tests) from current routing method
Having these thresholds allows you to quickly and easily tell at scale, and with impartial empiricism, what method is best for you and what changes might need to be made to better fit your requirements.
***
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
### Use a taxonomic hierarchy for cases with 20+ intent categories
As the number of classes grows, the number of examples required also expands, potentially making the prompt unwieldy. As an alternative, you can consider implementing a hierarchical classification system using a mixture of classifiers.
1. Organize your intents in a taxonomic tree structure.
2. Create a series of classifiers at every level of the tree, enabling a cascading routing approach.
For example, you might have a top-level classifier that broadly categorizes tickets into "Technical Issues," "Billing Questions," and "General Inquiries." Each of these categories can then have its own sub-classifier to further refine the classification.
* **Pros - greater nuance and accuracy:** You can create different prompts for each parent path, allowing for more targeted and context-specific classification. This can lead to improved accuracy and more nuanced handling of customer requests.
* **Cons - increased latency:** Be advised that multiple classifiers can lead to increased latency, and we recommend implementing this approach with our fastest model, Haiku.
### Use vector databases and similarity search retrieval to handle highly variable tickets
Despite providing examples being the most effective way to improve performance, if support requests are highly variable, it can be hard to include enough examples in a single prompt.
In this scenario, you could employ a vector database to do similarity searches from a dataset of examples and retrieve the most relevant examples for a given query.
This approach, outlined in detail in our [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide), has been shown to improve performance from 71% accuracy to 93% accuracy.
### Account specifically for expected edge cases
Here are some scenarios where Claude may misclassify tickets (there may be others that are unique to your situation). In these scenarios,consider providing explicit instructions or examples in the prompt of how Claude should handle the edge case:
<section title="Customers make implicit requests">
Customers often express needs indirectly. For example, "I've been waiting for my package for over two weeks now" may be an indirect request for order status.
* **Solution:** Provide Claude with some real customer examples of these kinds of requests, along with what the underlying intent is. You can get even better results if you include a classification rationale for particularly nuanced ticket intents, so that Claude can better generalize the logic to other tickets.
</section>
<section title="Claude prioritizes emotion over intent">
When customers express dissatisfaction, Claude may prioritize addressing the emotion over solving the underlying problem.
* **Solution:** Provide Claude with directions on when to prioritize customer sentiment or not. It can be something as simple as “Ignore all customer emotions. Focus only on analyzing the intent of the customer’s request and what information the customer might be asking for.”
</section>
<section title="Multiple issues cause issue prioritization confusion">
When customers present multiple issues in a single interaction, Claude may have difficulty identifying the primary concern.
* **Solution:** Clarify the prioritization of intents so thatClaude can better rank the extracted intents and identify the primary concern.
</section>
***
## Integrate Claude into your greater support workflow
Proper integration requires that you make some decisions regarding how your Claude-based ticket routing script fits into the architecture of your greater ticket routing system.There are two ways you could do this:
* **Push-based:** The support ticket system you’re using (e.g. Zendesk) triggers your code by sending a webhook event to your routing service, which then classifies the intent and routes it.
* This approach is more web-scalable, but needs you to expose a public endpoint.
* **Pull-Based:** Your code pulls for the latest tickets based on a given schedule and routes them at pull time.
* This approach is easier to implement but might make unnecessary calls to the support ticket system when the pull frequency is too high or might be overly slow when the pull frequency is too low.
For either of these approaches, you need to wrap your script in a service. The choice of approach depends on what APIs your support ticketing system provides.
***
<CardGroup cols={2}>
<Card title="Classification cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-classification-guide">
Visit our classification cookbook for more example code and detailed eval guidance.
</Card>
<Card title="Claude Console" icon="link" href="/dashboard">
Begin building and evaluating your workflow on the Claude Console.
</Card>
</CardGroup>
---
## Admin/api-admin-analytics-artifacts-c2ace4e523.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fartifacts)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Get Artifact Activity
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Artifacts
##### [Get Artifact Activity](/docs/en/api/http/admin/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
##### Models
ArtifactUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/artifacts.
`next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints.
---
## Admin/api-admin-analytics-artifacts-list-593f739ad4.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fartifacts%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Get Artifact Activity
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Artifacts](/docs/en/api/http/admin/analytics/artifacts)
# Get Artifact Activity
GET/v1/organizations/analytics/artifacts
Get artifact-creation activity for a given day, broken out by MIME type.
Returns the full (`artifact_type`, `is_shared`) cube for the organization; `next_page` is null except for grouped queries, which paginate. The cube can be broken out per product, per member, or per RBAC group via `group_by[]`, and scoped via `filter[]`. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: string
UTC date in YYYY-MM-DD format. The day to get artifact activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `artifact_type`, `is_shared`, `product`, `rbac_group_id`, `user_id`. Value forms: `artifact_type` is a canonical artifact MIME type (e.g. `text/markdown`) or `other`; `is_shared` is `true` or `false`; `product` is `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by: `product`, `user_id` and/or `rbac_group_id`. The ungrouped artifact-type cube is finite and returned in full; grouped queries multiply the cube and paginate via `next_page`. `product` takes the values `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts). `rbac_group_id` attributes a user to every group they held at any point during the requested UTC day, so grouped rows are not an exclusive partition. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Maximum rows to return (1-1000, default 100). The ungrouped artifact-type cube is finite and returned in full; `limit` is the page size only when `group_by[]` multiplies the cube.
minimum1
maximum1000
page: optional string
Opaque cursor from a previous response's `next_page` field. Only valid with `group_by[]` — the ungrouped cube is never paginated.
##### Returns
ArtifactUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/artifacts.
`next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints.
Get Artifact Activity
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/artifacts \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"artifact_type": "artifact_type",
"artifacts_created_count": 0,
"distinct_user_count": 0,
"is_shared": true,
"published_artifacts_created_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"artifact_type": "artifact_type",
"artifacts_created_count": 0,
"distinct_user_count": 0,
"is_shared": true,
"published_artifacts_created_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-admin-analytics-ca7855dc8a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fanalytics)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
# Analytics
##### [Get Activity Summaries](/docs/en/api/http/beta/organization/analytics/retrieve_summaries)
GET/v1/organizations/analytics/summaries
Get organization-wide activity summaries for a date range.
##### Models
BetaActivitySummary object{ summaries }
Response for GET /v1/organizations/analytics/summaries.
BetaAnalyticsUser object{ type: "user", id, email_address }
A user in the organization, identified by tagged id and email address.
type: "user"
Object type. Always `user`.
defaultuser
id: string
Tagged user identifier (e.g. `user_...`)
email_address: string
Email address of the user
BetaAnalyticsUserActor object{ type: "user_actor", deleted, email, 2 more }
type: "user_actor"
Actor type. Always `"user_actor"`.
deleted: boolean
True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation.
email: string or null
The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`).
name: string or null
The user's full name. Null when the user has not set a name. Returns `"Deleted User"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `"Claude Security"` for usage by Anthropic's security-patching service) or null.
user_id: string
Tagged user ID.
BetaConnectorOfficeProductMetrics object{ distinct_session_connector_used_count }
Office Agent activity metrics for a single connector on a given day within one Office product.
distinct_session_connector_used_count: number or null
Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
BetaOfficeProductMetrics object{ connectors_used_count, distinct_connectors_used_count, distinct_session_count, 3 more }
Office Agent activity metrics for a single user on a given day within one Office product.
connectors_used_count: number
Number of MCP connector invocations
distinct_connectors_used_count: number or null
Number of distinct MCP connectors used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
distinct_session_count: number or null
Number of distinct Office Agent sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
distinct_skills_used_count: number or null
Number of distinct skills used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
message_count: number
Number of messages sent
skills_used_count: number
Number of skill invocations
BetaSkillOfficeProductMetrics object{ distinct_session_skill_used_count }
Office Agent activity metrics for a single skill on a given day within one Office product.
distinct_session_skill_used_count: number or null
Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
BetaToolActionCounts object{ accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
rejected_count: number
Number of tool proposals rejected
#### Analytics[Usage](/docs/en/api/http/beta/organization/analytics/usage)
##### [Get Token Usage Over Time](/docs/en/api/http/beta/organization/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
Get token usage over time across a date range.
##### [Get Per-User Token Usage](/docs/en/api/http/beta/organization/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
Get per-user token usage across a date range.
#### Analytics[Cost](/docs/en/api/http/beta/organization/analytics/cost)
##### [Get Cost Over Time](/docs/en/api/http/beta/organization/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
Get cost in USD over time across a date range.
##### [Get Per-User Cost](/docs/en/api/http/beta/organization/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
Get per-user cost in USD across a date range.
#### Analytics[Users](/docs/en/api/http/beta/organization/analytics/users)
##### [List User Activity](/docs/en/api/http/beta/organization/analytics/users/list)
GET/v1/organizations/analytics/users
Get per-user activity for a given day, with cursor-based pagination.
#### Analytics[Skills](/docs/en/api/http/beta/organization/analytics/skills)
##### [Get Skill Usage](/docs/en/api/http/beta/organization/analytics/skills/list)
GET/v1/organizations/analytics/skills
Get per-skill usage for a given day, with cursor-based pagination.
#### Analytics[Connectors](/docs/en/api/http/beta/organization/analytics/connectors)
##### [Get Connector Usage](/docs/en/api/http/beta/organization/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
Get per-connector usage for a given day, with cursor-based pagination.
#### Analytics[Chat Projects](/docs/en/api/http/beta/organization/analytics/chat_projects)
##### [Get Chat Project Usage](/docs/en/api/http/beta/organization/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
Get per-project activity for a given day, with cursor-based pagination.
#### Analytics[Plugins](/docs/en/api/http/beta/organization/analytics/plugins)
##### [Get Plugin Usage](/docs/en/api/http/beta/organization/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
Get per-plugin install + invocation usage for a given day, with pagination.
#### Analytics[Artifacts](/docs/en/api/http/beta/organization/analytics/artifacts)
##### [Get Artifact Activity](/docs/en/api/http/beta/organization/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
Get artifact-creation activity for a given day, broken out by MIME type.
---
## Admin/api-admin-analytics-chat-projects-22f6e2335a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fchat_projects)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Get Chat Project Usage
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Chat Projects
##### [Get Chat Project Usage](/docs/en/api/http/admin/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
##### Models
ChatProjectUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
---
## Admin/api-admin-analytics-chat-projects-list-08cba7faad.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fchat_projects%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Get Chat Project Usage
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Chat Projects](/docs/en/api/http/admin/analytics/chat_projects)
# Get Chat Project Usage
GET/v1/organizations/analytics/apps/chat/projects
Get per-project activity for a given day, with cursor-based pagination.
Returns activity metrics for each project in the organization, sorted by project ID. Use `group_by[]` to break projects out per member or per RBAC group, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get project activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
ChatProjectUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
Get Chat Project Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"distinct_user_count": 0,
"message_count": 0,
"project_id": "project_id",
"project_name": "project_name",
"created_at": "2019-12-27T18:11:19.117Z",
"created_by": {
"id": "id",
"email_address": "email_address",
"type": "user"
},
"distinct_conversation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"distinct_user_count": 0,
"message_count": 0,
"project_id": "project_id",
"project_name": "project_name",
"created_at": "2019-12-27T18:11:19.117Z",
"created_by": {
"id": "id",
"email_address": "email_address",
"type": "user"
},
"distinct_conversation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-admin-analytics-connectors-27c86a7473.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fconnectors)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Get Connector Usage
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Connectors
##### [Get Connector Usage](/docs/en/api/http/admin/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
##### Models
ConnectorUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/connectors.
---
## Admin/api-admin-analytics-connectors-list-7520ecef1a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fanalytics%2Fconnectors%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Get Connector Usage
Chat Projects
Plugins
Artifacts
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Analytics](/docs/en/api/http/beta/organization/analytics)
5. [Connectors](/docs/en/api/http/beta/organization/analytics/connectors)
# Get Connector Usage
GET/v1/organizations/analytics/connectors
Get per-connector usage for a given day, with cursor-based pagination.
Returns connector usage metrics for the organization, sorted by connector name. Connector names are normalized from their various sources — for example, "Atlassian MCP server" and "mcp-atlassian" both appear as "atlassian". Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get connector usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `connector_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `connector_name` matches case-insensitively, a display name such as 'GitHub MCP' also matches its normalized stored form ('github'), and for rows whose `connector_name` is an opaque connector id the connector's display name (`connector_display_name`) also matches; `product` is one of `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
BetaConnectorUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/connectors.
Get Connector Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/connectors \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_connector_used_count": 0
},
"claude_code_metrics": {
"distinct_session_connector_used_count": 0
},
"connector_name": "connector_name",
"cowork_metrics": {
"distinct_session_connector_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_connector_used_count": 0
},
"outlook": {
"distinct_session_connector_used_count": 0
},
"powerpoint": {
"distinct_session_connector_used_count": 0
},
"word": {
"distinct_session_connector_used_count": 0
}
},
"connector_display_name": "connector_display_name",
"individual_auth_distinct_user_count": 0,
"managed_auth_distinct_user_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"read_call_count": 0,
"unclassified_call_count": 0,
"user_id": "user_id",
"write_call_count": 0
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_connector_used_count": 0
},
"claude_code_metrics": {
"distinct_session_connector_used_count": 0
},
"connector_name": "connector_name",
"cowork_metrics": {
"distinct_session_connector_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_connector_used_count": 0
},
"outlook": {
"distinct_session_connector_used_count": 0
},
"powerpoint": {
"distinct_session_connector_used_count": 0
},
"word": {
"distinct_session_connector_used_count": 0
}
},
"connector_display_name": "connector_display_name",
"individual_auth_distinct_user_count": 0,
"managed_auth_distinct_user_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-admin-analytics-cost-f840ed94c9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fcost)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Cost
##### [Get Cost Over Time](/docs/en/api/http/admin/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
##### [Get Per-User Cost](/docs/en/api/http/admin/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
##### Models
CostBucket object{ data, data_refreshed_at, has_more, 2 more }
UserCost object{ data, data_refreshed_at, has_more, 2 more }
---
## Admin/api-admin-analytics-cost-list-7120d75eb0.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fcost%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Cost](/docs/en/api/http/admin/analytics/cost)
# Get Cost Over Time
GET/v1/organizations/analytics/cost_report
Get cost in USD over time across a date range.
Returns cost bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, speed, cost type, or token type. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
default1d
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more
Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"cost_type"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
"token_type"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256).
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
CostBucket object{ data, data_refreshed_at, has_more, 2 more }
Get Cost Over Time
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"amount": "amount",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"amount": "amount",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-admin-analytics-cost-list-by-user-3cb2ef4296.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fcost%2Flist_by_user)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Cost](/docs/en/api/http/admin/analytics/cost)
# Get Per-User Cost
GET/v1/organizations/analytics/user_cost_report
Get per-user cost in USD across a date range.
Returns one row per user, ranked by spend. Use this to see which users account for the most cost. Only cost attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/cost_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range.
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
exclude_deleted_users: optional boolean
If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual.
defaultfalse
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more
Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/cost_report` endpoint. The `product`, `model`, `context_window`, `inference_geo`, and `speed` dimensions — and the time bucket, when `bucket_width` is set — count toward `limit`. `cost_type` and `token_type` do not: `cost_type` returns one row per cost component (tokens, web search, code execution); `token_type` returns one row per token type, each with `cost_type: "tokens"`; combining both returns the per-token-type rows plus the web-search and code-execution rows. A page can therefore contain more rows than `limit` when `cost_type` or `token_type` is requested.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"cost_type"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
"token_type"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it.
default20
maximum1000
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
defaultdesc
One of the following:
"asc"
"desc"
order_by: optional "amount" or "list_amount"
Metric to rank actors by. Defaults to `amount`.
defaultamount
One of the following:
"amount"
"list_amount"
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UserCost object{ data, data_refreshed_at, has_more, 2 more }
Get Per-User Cost
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"amount": "41280.000000",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"list_amount": "51600.000000",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"amount": "41280.000000",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"list_amount": "51600.000000",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-admin-analytics-plugins-65d6604148.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fplugins)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Get Plugin Usage
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Plugins
##### [Get Plugin Usage](/docs/en/api/http/admin/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
##### Models
PluginUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/plugins.
---
## Admin/api-admin-analytics-plugins-list-9d1e98e8dd.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fanalytics%2Fplugins%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Get Plugin Usage
Artifacts
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Analytics](/docs/en/api/http/beta/organization/analytics)
5. [Plugins](/docs/en/api/http/beta/organization/analytics/plugins)
# Get Plugin Usage
GET/v1/organizations/analytics/plugins
Get per-plugin install + invocation usage for a given day, with pagination.
Returns plugin usage metrics for the organization across Cowork and Claude Code, sorted by plugin name. The `plugin_name` value `third-party` is an aggregate bucket, not a plugin: it collects plugin activity, from either surface, for which the reporting client did not provide a plugin name — so an organization's own plugins can contribute both to their own named rows and to this bucket. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface (Cowork / Claude Code), and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Requires an API key with the `read:analytics` scope. `starting_date` / `ending_date` select range-rollup mode like `/skills`.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get plugin usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `plugin_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `plugin_name` matches case-insensitively; `product` is `claude_code` or `cowork` (the only surfaces with plugin attribution); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. On this endpoint `product` takes the values `claude_code` or `cowork` only (the surfaces with plugin attribution). Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
BetaPluginUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/plugins.
Get Plugin Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/plugins \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"claude_code_metrics": {
"distinct_session_plugin_used_count": 0
},
"cowork_metrics": {
"distinct_session_plugin_used_count": 0
},
"distinct_user_count": 0,
"install_count": 0,
"invocation_count": 0,
"plugin_name": "plugin_name",
"plugin_id": "plugin_id",
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"claude_code_metrics": {
"distinct_session_plugin_used_count": 0
},
"cowork_metrics": {
"distinct_session_plugin_used_count": 0
},
"distinct_user_count": 0,
"install_count": 0,
"invocation_count": 0,
"plugin_name": "plugin_name",
"plugin_id": "plugin_id",
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-admin-analytics-retrieve-summaries-003c474985.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fretrieve_summaries)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Get Activity Summaries
GET/v1/organizations/analytics/summaries
Get organization-wide activity summaries for a date range.
Returns one entry per day from `starting_date` (inclusive) to `ending_date` (exclusive). Data is typically available with a 1-day lag and may be revised by a few percent over the following days: when `ending_date` is omitted it defaults to the most recent available day + 1, so the last entry covers the most recent available day. The series can be scoped to an RBAC group via `filter[]=rbac_group_id:{id}`. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_date: string
UTC date in YYYY-MM-DD format. Start of the date range (inclusive). Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive). Data is typically available with a 1-day lag, so this can be at most today — which is also the default when omitted, making the last entry cover the most recent available day. Data may be revised by a few percent over the following days. The range may span at most 366 days.
formatdate
filter: optional array of string
Filters as `dimension:value`. Only `rbac_group_id` is supported (e.g. `filter[]=rbac_group_id:{id}`); repeat the param to OR across groups. Scopes the whole day series to members of the matching group(s), re-aggregated from member-level activity — org-wide seat/invite fields and the adoption rates derived from them are null on scoped rows. `rbac_group_id` accepts the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each UTC day (time-of-usage attribution). At most 100 entries.
maxItems100
##### Returns
ActivitySummary object{ summaries }
Response for GET /v1/organizations/analytics/summaries.
Get Activity Summaries
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/summaries \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"summaries": [
{
"assigned_seat_count": 0,
"cowork_daily_active_user_count": 0,
"cowork_monthly_active_user_count": 0,
"cowork_weekly_active_user_count": 0,
"daily_active_user_count": 0,
"daily_adoption_rate": 0,
"ending_at": "2019-12-27T18:11:19.117Z",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "2019-12-27T18:11:19.117Z",
"weekly_active_user_count": 0,
"weekly_adoption_rate": 0,
"chat_daily_active_user_count": 0,
"chat_monthly_active_user_count": 0,
"chat_weekly_active_user_count": 0,
"claude_code_daily_active_user_count": 0,
"claude_code_monthly_active_user_count": 0,
"claude_code_weekly_active_user_count": 0,
"claude_design_daily_active_user_count": 0,
"claude_design_monthly_active_user_count": 0,
"claude_design_weekly_active_user_count": 0,
"office_agent_daily_active_user_count": 0,
"office_agent_monthly_active_user_count": 0,
"office_agent_weekly_active_user_count": 0,
"science_daily_active_user_count": 0,
"science_entitled_user_count": 0,
"science_monthly_active_user_count": 0,
"science_weekly_active_user_count": 0
}
]
}
```
##### Returns Examples
Response 200
```python
{
"summaries": [
{
"assigned_seat_count": 0,
"cowork_daily_active_user_count": 0,
"cowork_monthly_active_user_count": 0,
"cowork_weekly_active_user_count": 0,
"daily_active_user_count": 0,
"daily_adoption_rate": 0,
"ending_at": "2019-12-27T18:11:19.117Z",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "2019-12-27T18:11:19.117Z",
"weekly_active_user_count": 0,
"weekly_adoption_rate": 0,
"chat_daily_active_user_count": 0,
"chat_monthly_active_user_count": 0,
"chat_weekly_active_user_count": 0,
"claude_code_daily_active_user_count": 0,
"claude_code_monthly_active_user_count": 0,
"claude_code_weekly_active_user_count": 0,
"claude_design_daily_active_user_count": 0,
"claude_design_monthly_active_user_count": 0,
"claude_design_weekly_active_user_count": 0,
"office_agent_daily_active_user_count": 0,
"office_agent_monthly_active_user_count": 0,
"office_agent_weekly_active_user_count": 0,
"science_daily_active_user_count": 0,
"science_entitled_user_count": 0,
"science_monthly_active_user_count": 0,
"science_weekly_active_user_count": 0
---
## Admin/api-admin-analytics-skills-60ec939467.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fskills)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Get Skill Usage
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Skills
##### [Get Skill Usage](/docs/en/api/http/admin/analytics/skills/list)
GET/v1/organizations/analytics/skills
##### Models
SkillUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/skills.
---
## Admin/api-admin-analytics-skills-list-18521474ae.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fanalytics%2Fskills%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Get Skill Usage
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Analytics](/docs/en/api/http/beta/organization/analytics)
5. [Skills](/docs/en/api/http/beta/organization/analytics/skills)
# Get Skill Usage
GET/v1/organizations/analytics/skills
Get per-skill usage for a given day, with cursor-based pagination.
Returns skill usage metrics for the organization, sorted by skill name. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get skill usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `product`, `rbac_group_id`, `share_status`, `skill_name`, `user_id`. Value forms: `product` is one of `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `share_status` is one of `organization`, `private`, or `public`; `skill_name` matches case-insensitively; `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
BetaSkillUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/skills.
Get Skill Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/skills \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_skill_used_count": 0
},
"claude_code_metrics": {
"distinct_session_skill_used_count": 0
},
"cowork_metrics": {
"distinct_session_skill_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_skill_used_count": 0
},
"outlook": {
"distinct_session_skill_used_count": 0
},
"powerpoint": {
"distinct_session_skill_used_count": 0
},
"word": {
"distinct_session_skill_used_count": 0
}
},
"skill_name": "skill_name",
"attributed_list_price": "attributed_list_price",
"currency": "USD",
"enable_count": 0,
"estimated_overage_spend": "estimated_overage_spend",
"invocation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"share_status": "organization",
"skill_display_name": "skill_display_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_skill_used_count": 0
},
"claude_code_metrics": {
"distinct_session_skill_used_count": 0
},
"cowork_metrics": {
"distinct_session_skill_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_skill_used_count": 0
},
"outlook": {
"distinct_session_skill_used_count": 0
},
"powerpoint": {
"distinct_session_skill_used_count": 0
},
"word": {
"distinct_session_skill_used_count": 0
}
},
"skill_name": "skill_name",
"attributed_list_price": "attributed_list_price",
"currency": "USD",
"enable_count": 0,
"estimated_overage_spend": "estimated_overage_spend",
"invocation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"share_status": "organization",
"skill_display_name": "skill_display_name",
---
## Admin/api-admin-analytics-usage-35dfc78cdc.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fusage)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Usage
##### [Get Token Usage Over Time](/docs/en/api/http/admin/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
##### [Get Per-User Token Usage](/docs/en/api/http/admin/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
##### Models
UsageBucket object{ data, data_refreshed_at, has_more, 2 more }
UserUsage object{ data, data_refreshed_at, has_more, 2 more }
---
## Admin/api-admin-analytics-usage-list-a18d3dd5d2.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fusage%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Usage](/docs/en/api/http/admin/analytics/usage)
# Get Token Usage Over Time
GET/v1/organizations/analytics/usage_report
Get token usage over time across a date range.
Returns token usage bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, or speed. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
default1d
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more
Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256).
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UsageBucket object{ data, data_refreshed_at, has_more, 2 more }
Get Token Usage Over Time
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 0,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 0,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"uncached_input_tokens": 0
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 0,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 0,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"uncached_input_tokens": 0
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-admin-analytics-usage-list-by-user-fc5ac93d35.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fusage%2Flist_by_user)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Usage](/docs/en/api/http/admin/analytics/usage)
# Get Per-User Token Usage
GET/v1/organizations/analytics/user_usage_report
Get per-user token usage across a date range.
Returns one row per user, ranked by the chosen token metric. Use this to see which users consume the most tokens. Only usage attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/usage_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range.
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
exclude_deleted_users: optional boolean
If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual.
defaultfalse
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more
Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/usage_report` endpoint. `limit` bounds (actor × time bucket × dimension) rows — with dimensions or `bucket_width` present, one actor may span several rows.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it.
default20
maximum1000
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
defaultdesc
One of the following:
"asc"
"desc"
order_by: optional "output_tokens" or "requests" or "total_tokens" or "uncached_input_tokens"
Metric to rank actors by. Defaults to `total_tokens`.
defaulttotal_tokens
One of the following:
"output_tokens"
"requests"
"total_tokens"
"uncached_input_tokens"
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UserUsage object{ data, data_refreshed_at, has_more, 2 more }
Get Per-User Token Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 891000,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"total_tokens": 5377000,
"uncached_input_tokens": 1284500
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 891000,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"total_tokens": 5377000,
"uncached_input_tokens": 1284500
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-admin-analytics-users-95f1a89853.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fusers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
List User Activity
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Users
##### [List User Activity](/docs/en/api/http/admin/analytics/users/list)
GET/v1/organizations/analytics/users
##### Models
UserActivity object{ data, next_page }
Response for GET /v1/organizations/analytics/users.
---
## Admin/api-admin-analytics-users-list-e87db2f77e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fanalytics%2Fusers%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
List User Activity
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Users](/docs/en/api/http/admin/analytics/users)
# List User Activity
GET/v1/organizations/analytics/users
Get per-user activity for a given day, with cursor-based pagination.
Returns activity metrics for each user in the organization, sorted by email address. Use `group_by[]` for per-RBAC-group aggregates, or `filter[]` to scope results to specific members, groups, or a chat project. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get user activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`) and scopes each member's row to their claude.ai chat activity within that project (it cannot be combined with `group_by[]` or an `rbac_group_id` filter); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "rbac_group_id"
Dimensions to break results out by (e.g. `group_by[]=rbac_group_id`). Supported on this endpoint: `rbac_group_id`. Rows are already per-member, so the one supported grouping aggregates them per RBAC group instead. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
UserActivity object{ data, next_page }
Response for GET /v1/organizations/analytics/users.
List User Activity
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"connectors_used_count": 0,
"distinct_artifacts_created_count": 0,
"distinct_connectors_used_count": 0,
"distinct_conversation_count": 0,
"distinct_files_uploaded_count": 0,
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_shared_artifacts_viewed_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"shared_conversations_viewed_count": 0,
"thinking_message_count": 0
},
"claude_code_metrics": {
"core_metrics": {
"artifacts_created_count": 0,
"commit_count": 0,
"distinct_session_count": 0,
"lines_of_code": {
"added_count": 0,
"removed_count": 0
},
"pull_request_count": 0
},
"tool_actions": {
"edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"multi_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"notebook_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"write_tool": {
"accepted_count": 0,
"rejected_count": 0
}
}
},
"cowork_metrics": {
"action_count": 0,
"artifacts_created_count": 0,
"connectors_used_count": 0,
"dispatch_turn_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0,
"distinct_plugins_used_count": 0,
"edit_tool_count": 0,
"file_edit_count": 0,
"multi_edit_tool_count": 0,
"notebook_edit_tool_count": 0,
"plugins_used_count": 0,
"sessions_with_file_edits_count": 0,
"write_tool_count": 0
},
"design_metrics": {
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_session_count": 0,
"message_count": 0
},
"office_metrics": {
"excel": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"outlook": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"powerpoint": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"word": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
}
},
"science_metrics": {
"delegation_count": 0,
"distinct_session_count": 0,
"message_count": 0,
"remote_compute_job_count": 0,
"skills_used_count": 0
},
"web_search_count": 0,
"distinct_user_count": 0,
"last_activity_date": "2019-12-27",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user": {
"id": "id",
"email_address": "email_address",
"type": "user"
}
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"connectors_used_count": 0,
"distinct_artifacts_created_count": 0,
"distinct_connectors_used_count": 0,
"distinct_conversation_count": 0,
"distinct_files_uploaded_count": 0,
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_shared_artifacts_viewed_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"shared_conversations_viewed_count": 0,
"thinking_message_count": 0
},
"claude_code_metrics": {
"core_metrics": {
"artifacts_created_count": 0,
"commit_count": 0,
"distinct_session_count": 0,
"lines_of_code": {
"added_count": 0,
"removed_count": 0
},
"pull_request_count": 0
},
"tool_actions": {
"edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"multi_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"notebook_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"write_tool": {
"accepted_count": 0,
"rejected_count": 0
}
}
},
"cowork_metrics": {
"action_count": 0,
"artifacts_created_count": 0,
"connectors_used_count": 0,
"dispatch_turn_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0,
"distinct_plugins_used_count": 0,
"edit_tool_count": 0,
"file_edit_count": 0,
"multi_edit_tool_count": 0,
"notebook_edit_tool_count": 0,
"plugins_used_count": 0,
"sessions_with_file_edits_count": 0,
"write_tool_count": 0
},
"design_metrics": {
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_session_count": 0,
"message_count": 0
},
"office_metrics": {
"excel": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"outlook": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"powerpoint": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"word": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
}
},
"science_metrics": {
"delegation_count": 0,
"distinct_session_count": 0,
"message_count": 0,
"remote_compute_job_count": 0,
"skills_used_count": 0
},
"web_search_count": 0,
"distinct_user_count": 0,
"last_activity_date": "2019-12-27",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user": {
"id": "id",
"email_address": "email_address",
---
## Admin/api-admin-api-keys-5e6e893cb4.md
# API Keys
## Retrieve
**get** `/v1/organizations/api_keys/{api_key_id}`
Get API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/api_keys`
List API Keys
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `created_by_user_id: optional string`
Filter by the ID of the User who created the object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
- `status: optional "active" or "inactive" or "archived" or "expired"`
Filter by API key status.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `workspace_id: optional string`
Filter by Workspace ID.
### Returns
- `data: array of APIKey`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/api_keys/{api_key_id}`
Update API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Body Parameters
- `name: optional string`
Name of the API key.
- `status: optional "active" or "inactive" or "archived"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{}'
```
---
## Admin/api-admin-api-keys-8eedabf18b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fapi_keys)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
Retrieve API Key (Admin API)
List API Keys
Update API Key
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# API Keys
##### [Retrieve API Key (Admin API)](/docs/en/api/http/admin/api_keys/retrieve)
GET/v1/organizations/api_keys/{api_key_id}
##### [List API Keys](/docs/en/api/http/admin/api_keys/list)
GET/v1/organizations/api_keys
##### [Update API Key](/docs/en/api/http/admin/api_keys/update)
POST/v1/organizations/api_keys/{api_key_id}
---
## Admin/api-admin-api-keys-list-46c6242fe5.md
## List
**get** `/v1/organizations/api_keys`
List API Keys
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `created_by_user_id: optional string`
Filter by the ID of the User who created the object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
- `status: optional "active" or "inactive" or "archived" or "expired"`
Filter by API key status.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `workspace_id: optional string`
Filter by Workspace ID.
### Returns
- `data: array of APIKey`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-api-keys-list-8ec91325a8.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fapi_keys%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
List API Keys
Retrieve API Key (Admin API)
Update API Key
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [API Keys](/docs/en/api/http/beta/organization/api_keys)
# List API Keys
GET/v1/organizations/api_keys
List API Keys
##### Query parameters
after_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
created_by_user_id: optional string
Filter by the ID of the User who created the object.
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
status: optional "active" or "archived" or "expired" or "inactive"
Filter by API key status.
One of the following:
"active"
"archived"
"expired"
"inactive"
workspace_id: optional string
Filter by Workspace ID.
##### Returns
data: array of [BetaAPIKey](/docs/en/api/http/beta/organization/api_keys#beta_api_key) { type: "api_key", id, created_at, 8 more }
type: "api_key"
Object type.
For API Keys, this is always `"api_key"`.
defaultapi_key
id: string
ID of the API key.
created_at: string
RFC 3339 datetime string indicating when the API Key was created.
formatdate-time
created_by: [BetaAPIKeyCreatedBy](/docs/en/api/http/beta/organization/api_keys#beta_api_key_created_by) { type, id } or null
The ID and type of the actor that created the API key, or `null` when the creator is not recorded (legacy, workload-identity-federated, or system-created keys).
type: "service_account" or "user"
Type of the actor that created the object.
One of the following:
"service_account"
"user"
id: string
ID of the actor that created the object.
expires_at: string or null
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
formatdate-time
name: string
Name of the API key.
partial_key_hint: string or null
Partially redacted hint for the API key.
principal: [BetaAPIKeyUserActor](/docs/en/api/http/beta/organization/api_keys#beta_api_key_user_actor) or [BetaAPIKeyServiceAccountActor](/docs/en/api/http/beta/organization/api_keys#beta_api_key_service_account_actor) or null
The principal the API key acts as (a User or a Service Account), or `null` if the API key is not bound to a principal.
One of the following:
BetaAPIKeyUserActor object{ type: "user_actor", user_id }
type: "user_actor"
Principal type. Always `"user_actor"` for a User.
defaultuser_actor
user_id: string
ID of the User the API key acts as.
BetaAPIKeyServiceAccountActor object{ type: "service_account_actor", service_account_id }
type: "service_account_actor"
Principal type. Always `"service_account_actor"` for a Service Account.
defaultservice_account_actor
service_account_id: string
ID of the Service Account the API key acts as.
scope: [BetaAPIKeyOrganizationScope](/docs/en/api/http/beta/organization/api_keys#beta_api_key_organization_scope) or [BetaAPIKeyWorkspaceScope](/docs/en/api/http/beta/organization/api_keys#beta_api_key_workspace_scope)
Where the API key belongs: its Workspace (`{"type": "workspace", "workspace_id": "wrkspc_..."}`, with the Workspace's real ID even when it is the organization's default Workspace), or the organization (`{"type": "organization"}`) for a principal-bound API key that has no Workspace.
One of the following:
BetaAPIKeyOrganizationScope object{ type: "organization" }
type: "organization"
Scope type. Always `"organization"`: the API key has no Workspace. Only a principal-bound API key can have this scope.
defaultorganization
BetaAPIKeyWorkspaceScope object{ type: "workspace", workspace_id }
type: "workspace"
Scope type. Always `"workspace"`: the API key belongs to one Workspace.
defaultworkspace
workspace_id: string
ID of the Workspace the API key belongs to. Unlike the deprecated top-level `workspace_id`, this is the Workspace's real ID even for the organization's default Workspace.
status: "active" or "archived" or "expired" or "inactive"
Status of the API key.
One of the following:
"active"
"archived"
"expired"
"inactive"
workspace_id: string or nullDeprecated
Deprecated: use `scope` instead. ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace. Also `null` for a principal-bound API key that has no Workspace; `scope` tells the two apart.
Use \`scope\` instead. \`workspace_id\` is \`null\` both for an API key in the default Workspace and for a principal-bound API key that has no Workspace.
first_id: string or null
First ID in the `data` list. Can be used as the `before_id` for the previous page.
has_more: boolean
Indicates if there are more results in the requested page direction.
last_id: string or null
Last ID in the `data` list. Can be used as the `after_id` for the next page.
List API Keys
cURL
```python
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-api-keys-retrieve-1be8681752.md
## Retrieve
**get** `/v1/organizations/api_keys/{api_key_id}`
Get API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-api-keys-retrieve-a53c55f75c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fapi_keys%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
Retrieve API Key (Admin API)
List API Keys
Update API Key
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [API Keys](/docs/en/api/http/admin/api_keys)
# Retrieve API Key (Admin API)
GET/v1/organizations/api_keys/{api_key_id}
Retrieve information about a single API key in your organization, looked up by its ID. This Admin API endpoint requires an Admin API key, is intended for programmatic key management, and never returns the key's secret value. To view or create your own API keys, go to [API keys](https://platform.claude.com/settings/keys) in the Claude Console.
##### Path parameters
api_key_id: string
ID of the API key.
##### Returns
APIKey object{ id, created_at, created_by, 8 more }
Retrieve API Key (Admin API)
cURL
```python
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
```
##### Returns Examples
Response 200
```python
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-api-keys-update-2d5070e66f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fapi_keys%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
Retrieve API Key (Admin API)
List API Keys
Update API Key
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [API Keys](/docs/en/api/http/admin/api_keys)
# Update API Key
POST/v1/organizations/api_keys/{api_key_id}
Update API Key
##### Path parameters
api_key_id: string
ID of the API key.
##### Body
name: optional string or null
Name of the API key.
maxLength500
minLength1
status: optional "active" or "archived" or "inactive" or null
Status of the API key.
One of the following:
"active"
"archived"
"inactive"
##### Returns
APIKey object{ id, created_at, created_by, 8 more }
Update API Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
```
##### Returns Examples
Response 200
```python
{
"id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"expires_at": "2024-10-30T23:58:27.427722Z",
"name": "Developer Key",
"partial_key_hint": "sk-ant-api03-R2D...igAA",
"principal": {
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"scope": {
"type": "workspace",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
},
"status": "active",
"type": "api_key",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-api-keys-update-f2523628a4.md
## Update
**post** `/v1/organizations/api_keys/{api_key_id}`
Update API Key
### Path Parameters
- `api_key_id: string`
ID of the API key.
### Body Parameters
- `name: optional string`
Name of the API key.
- `status: optional "active" or "inactive" or "archived"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
### Returns
- `APIKey = object { id, created_at, created_by, 6 more }`
- `id: string`
ID of the API key.
- `created_at: string`
RFC 3339 datetime string indicating when the API Key was created.
- `created_by: object { id, type }`
The ID and type of the actor that created the API key.
- `id: string`
ID of the actor that created the object.
- `type: string`
Type of the actor that created the object.
- `expires_at: string`
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
- `name: string`
Name of the API key.
- `partial_key_hint: string`
Partially redacted hint for the API key.
- `status: "active" or "inactive" or "archived" or "expired"`
Status of the API key.
- `"active"`
- `"inactive"`
- `"archived"`
- `"expired"`
- `type: "api_key"`
Object type.
For API Keys, this is always `"api_key"`.
- `"api_key"`
- `workspace_id: string`
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{}'
```
---
## Admin/api-admin-cost-report-775f37e73b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fcost_report)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Get Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Cost Report
##### [Get Cost Report](/docs/en/api/http/admin/cost_report/retrieve)
GET/v1/organizations/cost_report
##### Models
CostReport object{ data, has_more, next_page }
---
## Admin/api-admin-cost-report-ec1d585117.md
# Cost Report
## Retrieve
**get** `/v1/organizations/cost_report`
Get Cost Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `bucket_width: optional "1d"`
Time granularity of the response data.
- `"1d"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "workspace_id" or "description"`
Group by any subset of the available options.
- `"workspace_id"`
- `"description"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Cost Report
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-cost-report-retrieve-45422adc34.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fcost_report%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Get Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Cost Report](/docs/en/api/http/admin/cost_report)
# Get Cost Report
GET/v1/organizations/cost_report
Get Cost Report
##### Query parameters
starting_at: string
Time buckets that start on or after this RFC 3339 timestamp will be returned. Each time bucket will be snapped to the start of the minute/hour/day in UTC.
formatdate-time
bucket_width: optional "1d"
Time granularity of the response data.
default1d
ending_at: optional string
Time buckets that end before this RFC 3339 timestamp will be returned.
formatdate-time
group_by: optional array of "description" or "workspace_id"
Group by any subset of the available options.
One of the following:
"description"
"workspace_id"
limit: optional number
Maximum number of time buckets to return in the response.
default7
maximum31
minimum1
page: optional string
Optionally set to the `next_page` token from the previous response.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
CostReport object{ data, has_more, next_page }
Get Cost Report
cURL
```python
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"ending_at": "2025-08-02T00:00:00Z",
"results": [
{
"amount": "123.78912",
"context_window": "0-200k",
"cost_type": "tokens",
"currency": "USD",
"description": "Claude Opus 5 Usage - Input Tokens",
"inference_geo": "global",
"model": "claude-opus-5",
"service_tier": "standard",
"token_type": "uncached_input_tokens",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2025-08-02T00:00:00Z",
"results": [
{
"amount": "123.78912",
"context_window": "0-200k",
"cost_type": "tokens",
"currency": "USD",
"description": "Claude Opus 5 Usage - Input Tokens",
"inference_geo": "global",
"model": "claude-opus-5",
"service_tier": "standard",
"token_type": "uncached_input_tokens",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
---
## Admin/api-admin-cost-report-retrieve-86a0323049.md
## Retrieve
**get** `/v1/organizations/cost_report`
Get Cost Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `bucket_width: optional "1d"`
Time granularity of the response data.
- `"1d"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "workspace_id" or "description"`
Group by any subset of the available options.
- `"workspace_id"`
- `"description"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `CostReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { amount, context_window, cost_type, 7 more }`
List of cost items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `amount: string`
Cost amount in lowest currency units (e.g. cents) as a decimal string. For example, `"123.45"` in `"USD"` represents `$1.23`.
- `context_window: "0-200k" or "200k-1M"`
Input context window used. `null` if not grouping by description or for non-token costs.
- `"0-200k"`
- `"200k-1M"`
- `cost_type: "tokens" or "web_search" or "code_execution" or "session_usage"`
Type of cost. `null` if not grouping by description.
- `"tokens"`
- `"web_search"`
- `"code_execution"`
- `"session_usage"`
- `currency: string`
Currency code for the cost amount. Currently always `"USD"`.
- `description: string`
Description of the cost item. `null` if not grouping by description.
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model name used. `null` if not grouping by description or for non-token costs.
- `service_tier: "standard" or "batch"`
Service tier used. `null` if not grouping by description or for non-token costs.
- `"standard"`
- `"batch"`
- `token_type: "uncached_input_tokens" or "output_tokens" or "cache_read_input_tokens" or 2 more`
Type of token. `null` if not grouping by description or for non-token costs.
- `"uncached_input_tokens"`
- `"output_tokens"`
- `"cache_read_input_tokens"`
- `"cache_creation.ephemeral_1h_input_tokens"`
- `"cache_creation.ephemeral_5m_input_tokens"`
- `workspace_id: string`
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-external-keys-create-9746b93b8f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# Create External Key
POST/v1/organizations/external_keys
Create an external key config owned by the caller's organization.
##### Body
provider_config: object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more }
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
Azure Key Vault provider configuration.
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
display_name: optional string or null
Human-friendly display name.
maxLength255
minLength1
geo: optional "us"
Data residency geo. Only `us` is supported.
##### Returns
id: string
Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN.
attachment: object{ type } or object{ type }
Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted.
One of the following:
Attached object{ type }
type: "attached"
defaultattached
Unattached object{ type }
type: "unattached"
defaultunattached
created_at: string
formatdate-time
display_name: string or null
Human-friendly display name. Null if none was set.
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
provider_config: object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more }
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
type: "external_key"
defaultexternal_key
updated_at: string
formatdate-time
Create External Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws"
}
}'
```
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-external-keys-delete-ceda5828fe.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# Delete External Key
DELETE/v1/organizations/external_keys/{external_key_id}
Delete an external key config.
The request is rejected if any workspace still references this config.
##### Path parameters
external_key_id: string
ID of the External Key.
maxLength2048
##### Returns
id: string
ID of the deleted External Key.
type: "external_key_deleted"
defaultexternal_key_deleted
Delete External Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys/$EXTERNAL_KEY_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "ekey_01AbCdEfGhIjKlMnOpQrStUv",
"type": "external_key_deleted"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ekey_01AbCdEfGhIjKlMnOpQrStUv",
"type": "external_key_deleted"
---
## Admin/api-admin-external-keys-f7a4752b81.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# External Keys
##### [Create External Key](/docs/en/api/http/admin/external_keys/create)
POST/v1/organizations/external_keys
##### [List External Keys](/docs/en/api/http/admin/external_keys/list)
GET/v1/organizations/external_keys
##### [Get External Key](/docs/en/api/http/admin/external_keys/retrieve)
GET/v1/organizations/external_keys/{external_key_id}
##### [Update External Key](/docs/en/api/http/admin/external_keys/update)
POST/v1/organizations/external_keys/{external_key_id}
##### [Delete External Key](/docs/en/api/http/admin/external_keys/delete)
DELETE/v1/organizations/external_keys/{external_key_id}
##### [Validate External Key](/docs/en/api/http/admin/external_keys/validate)
POST/v1/organizations/external_keys/{external_key_id}/validate
##### Models
ExternalKeyCreateResponse object{ id, attachment, created_at, 5 more }
CMEK external key config belonging to the caller's organization.
Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt).
ExternalKeyRetrieveResponse object{ id, attachment, created_at, 5 more }
CMEK external key config belonging to the caller's organization.
Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt).
ExternalKeyUpdateResponse object{ id, attachment, created_at, 5 more }
CMEK external key config belonging to the caller's organization.
Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt).
ExternalKeyListResponse object{ id, attachment, created_at, 5 more }
CMEK external key config belonging to the caller's organization.
Configs are organization-scoped. Workspaces attach to a config; once any workspace references it, the provider fields become effectively immutable (existing encrypted data needs the config for decrypt).
ExternalKeyDeleteResponse object{ id, type }
id: string
ID of the deleted External Key.
type: "external_key_deleted"
defaultexternal_key_deleted
ExternalKeyValidateResponse object{ error, status, type }
Result of a validation roundtrip against the customer's KMS.
HTTP 200 for both outcomes — the operation completed; `status` says whether the key works.
error: string or null
Error message when status is `failure`. Null otherwise.
status: "failure" or "success"
`success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`.
One of the following:
"failure"
"success"
type: "external_key_validation"
defaultexternal_key_validation
---
## Admin/api-admin-external-keys-list-9f1dc75db6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# List External Keys
GET/v1/organizations/external_keys
List external key configs in the caller's organization.
Results are ordered by creation time (newest first). Use the `next_page` cursor from the response to fetch subsequent pages.
##### Query parameters
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Returns
data: array of object{ id, attachment, created_at, 5 more }
id: string
Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN.
attachment: object{ type } or object{ type }
Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted.
One of the following:
Attached object{ type }
type: "attached"
defaultattached
Unattached object{ type }
type: "unattached"
defaultunattached
created_at: string
formatdate-time
display_name: string or null
Human-friendly display name. Null if none was set.
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
provider_config: object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more }
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
type: "external_key"
defaultexternal_key
updated_at: string
formatdate-time
next_page: string or null
Opaque cursor for the next page, or null if no more results. Pass as `?page=` to fetch the next page.
List External Keys
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-external-keys-retrieve-c8e2f4efcc.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# Get External Key
GET/v1/organizations/external_keys/{external_key_id}
Retrieve a single external key config in the caller's organization by ID.
##### Path parameters
external_key_id: string
ID of the External Key.
maxLength2048
##### Returns
id: string
Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN.
attachment: object{ type } or object{ type }
Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted.
One of the following:
Attached object{ type }
type: "attached"
defaultattached
Unattached object{ type }
type: "unattached"
defaultunattached
created_at: string
formatdate-time
display_name: string or null
Human-friendly display name. Null if none was set.
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
provider_config: object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more }
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
type: "external_key"
defaultexternal_key
updated_at: string
formatdate-time
Get External Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys/$EXTERNAL_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-external-keys-update-adad1d6546.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# Update External Key
POST/v1/organizations/external_keys/{external_key_id}
Partially update an external key config. Omitted fields are left unchanged.
`display_name` is always editable. `geo` and `provider_config` cannot be changed once any workspace references this config, because previously encrypted data requires the original key identity to decrypt.
##### Path parameters
external_key_id: string
ID of the External Key.
maxLength2048
##### Body
display_name: optional string or null
Human-friendly display name.
maxLength255
minLength1
geo: optional "us" or null
Data residency geo. Only `us` is supported.
provider_config: optional object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more } or null
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
Azure Key Vault provider configuration.
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
##### Returns
id: string
Identifier of the external key config. A tagged ID prefixed `ekey_`, or — for organizations on the Claude Platform on AWS — the AWS KMS key ARN.
attachment: object{ type } or object{ type }
Whether any workspace uses this config to encrypt its data — counting live and archived workspaces (an archived workspace's data remains encrypted under the config), excluding deleted ones. Only an attached config is used by the encryption path; an `unattached` config is inert and can be deleted.
One of the following:
Attached object{ type }
type: "attached"
defaultattached
Unattached object{ type }
type: "unattached"
defaultunattached
created_at: string
formatdate-time
display_name: string or null
Human-friendly display name. Null if none was set.
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
provider_config: object{ kms_arn, type, region, role_arn } or object{ key_name, type } or object{ key_name, tenant_id, type, 2 more }
KMS provider identity and auth coordinates.
One of the following:
Aws object{ kms_arn, type, region, role_arn }
kms_arn: string
Full ARN of the AWS KMS key. On Claude Platform on AWS the key must be a single-Region key in your organization's own AWS account; cross-account keys, multi-Region keys, and alias ARNs are rejected.
maxLength2048
type: "aws"
region: optional string or null
AWS region. Derived from `kms_arn` if omitted.
role_arn: optional string or nullDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key through its own intermediate role (or, on Claude Platform on AWS, with credentials AWS issues for the Workspace); this field is ignored.
Gcp object{ key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
type: "gcp"
Azure object{ key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
tenant_id: string
Azure AD tenant ID.
type: "azure"
vault_uri: string
Key Vault data-plane URI — `https://{vault-name}.vault.azure.net` or `https://{hsm-name}.managedhsm.azure.net`.
client_id: optional string or null
Azure AD application (client) ID. Omit to use Anthropic's multitenant app. Provide only if using a single-tenant app registration in the customer's directory.
type: "external_key"
defaultexternal_key
updated_at: string
formatdate-time
Update External Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys/$EXTERNAL_KEY_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"attachment": {
"type": "attached"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "prod-us-key",
"geo": "us",
"provider_config": {
"kms_arn": "arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-000011112222",
"type": "aws",
"region": "us-east-1",
"role_arn": "arn:aws:iam::111122223333:role/anthropic-cmek"
},
"type": "external_key",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-external-keys-validate-8c81626c8c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fexternal_keys%2Fvalidate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Create External Key
List External Keys
Get External Key
Update External Key
Delete External Key
Validate External Key
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [External Keys](/docs/en/api/http/admin/external_keys)
# Validate External Key
POST/v1/organizations/external_keys/{external_key_id}/validate
Validate an external key config against the customer's KMS.
Anthropic performs an encrypt/decrypt roundtrip against the configured KMS key and waits up to 30 seconds for the result. The response status is `success` if the roundtrip succeeded, or `failure` with an error message if it failed or timed out.
##### Path parameters
external_key_id: string
ID of the External Key.
maxLength2048
##### Returns
error: string or null
Error message when status is `failure`. Null otherwise.
status: "failure" or "success"
`success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`.
One of the following:
"failure"
"success"
type: "external_key_validation"
defaultexternal_key_validation
Validate External Key
cURL
```python
curl https://api.anthropic.com/v1/organizations/external_keys/$EXTERNAL_KEY_ID/validate \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"error": null,
"status": "success",
"type": "external_key_validation"
}
```
##### Returns Examples
Response 200
```python
{
"error": null,
"status": "success",
"type": "external_key_validation"
---
## Admin/api-admin-federation-issuers-0a30d0bcd6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Federation Issuers
##### [Create Federation Issuer](/docs/en/api/http/admin/federation_issuers/create)
POST/v1/organizations/federation_issuers
##### [Get Federation Issuer](/docs/en/api/http/admin/federation_issuers/retrieve)
GET/v1/organizations/federation_issuers/{federation_issuer_id}
##### [List Federation Issuers](/docs/en/api/http/admin/federation_issuers/list)
GET/v1/organizations/federation_issuers
##### [Update Federation Issuer](/docs/en/api/http/admin/federation_issuers/update)
POST/v1/organizations/federation_issuers/{federation_issuer_id}
##### [Archive Federation Issuer](/docs/en/api/http/admin/federation_issuers/archive)
POST/v1/organizations/federation_issuers/{federation_issuer_id}/archive
##### Models
FederationIssuer object{ id, archived_at, archived_by_actor_id, 12 more }
Registered external OIDC identity provider.
Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.
---
## Admin/api-admin-federation-issuers-archive-158ebf63de.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers%2Farchive)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Issuers](/docs/en/api/http/admin/federation_issuers)
# Archive Federation Issuer
POST/v1/organizations/federation_issuers/{federation_issuer_id}/archive
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Archive a federation issuer.
Idempotent; re-archiving returns the issuer with its original `archived_at`. Rejected with 400 if any live (non-archived) federation rule still references the issuer; archive those rules first (a rule's issuer cannot be changed), or recreate them against another issuer.
##### Path parameters
federation_issuer_id: string
ID of the federation issuer to archive.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
FederationIssuer object{ id, archived_at, archived_by_actor_id, 12 more }
Registered external OIDC identity provider.
Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.
Archive Federation Issuer
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers/$FEDERATION_ISSUER_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-federation-issuers-create-d54472467a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Issuers](/docs/en/api/http/admin/federation_issuers)
# Create Federation Issuer
POST/v1/organizations/federation_issuers
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Register an OIDC issuer that Anthropic will trust for workload identity federation in your organization.
The `jwks` field controls how the issuer's signing keys are obtained and takes one of three shapes selected by `type`: `discovery` (resolve keys through OIDC discovery), `explicit_url` (fetch keys from a fixed JWKS URL), or `inline` (provide a static key set). When `jwks.type` is `discovery` and no `discovery_base` is set, the issuer URL must be publicly reachable over HTTPS so Anthropic can fetch the discovery document; for `explicit_url` and `inline` modes the issuer URL is only matched as the JWT's `iss` claim and is not fetched.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
issuer_url: string
The `iss` claim value to match against.
minLength1
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
maxLength255
minLength1
check_jti: optional boolean or null
Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Defaults to true. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement.
jwks: optional object{ type, ca_cert_pem, discovery_base } or object{ type, url, ca_cert_pem } or object{ keys, type }
How signing keys are obtained. Defaults to OIDC discovery.
One of the following:
Discovery object{ type, ca_cert_pem, discovery_base }
JWKS via the issuer's OIDC discovery document.
type: "discovery"
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
discovery_base: optional string or null
Set when the discovery URL differs from `issuer_url`.
ExplicitURL object{ type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
url: string
JWKS endpoint.
minLength1
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
Inline object{ keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
minItems1
type: "inline"
max_jwt_lifetime_seconds: optional number or null
Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Defaults to 3600 (1h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected.
maximum176400
exclusiveMinimum0
##### Returns
FederationIssuer object{ id, archived_at, archived_by_actor_id, 12 more }
Registered external OIDC identity provider.
Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.
Create Federation Issuer
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"issuer_url": "x",
"name": "x"
}'
```
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-federation-issuers-list-c2842d69f9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Issuers](/docs/en/api/http/admin/federation_issuers)
# List Federation Issuers
GET/v1/organizations/federation_issuers
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List federation issuers in your organization.
Archived issuers are excluded unless `include_archived=true`.
##### Query parameters
include_archived: optional boolean
Include archived resources. Defaults to false.
defaultfalse
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of [FederationIssuer](/docs/en/api/http/admin/federation_issuers#federation_issuer) { id, archived_at, archived_by_actor_id, 12 more }
id: string
Tagged ID of the federation issuer.
archived_at: string or null
If set, all rules referencing this issuer reject token exchange.
formatdate-time
archived_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
check_jti: boolean
Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement.
created_at: string
When this issuer was created.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
jwks: object{ type, ca_cert_pem, discovery_base } or object{ type, url, ca_cert_pem } or object{ keys, type }
How signing keys are obtained for signature verification.
One of the following:
Discovery object{ type, ca_cert_pem, discovery_base }
JWKS via the issuer's OIDC discovery document.
type: "discovery"
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
discovery_base: optional string or null
Set when the discovery URL differs from `issuer_url`.
ExplicitURL object{ type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
url: string
JWKS endpoint.
minLength1
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
Inline object{ keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
minItems1
type: "inline"
jwks_polling_disabled_at: string or null
If set, Anthropic's JWKS poller has paused polling for this issuer after repeated fetch failures. Re-enable by sending `jwks_polling_disabled: false` via the issuer update endpoint (POST) once the upstream JWKS endpoint is fixed. An OAuth caller cannot send this when the issuer backs a rule with any scope other than `workspace:developer` or `workspace:inference`; use a Console session.
formatdate-time
max_jwt_lifetime_seconds: number
Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected.
name: string
Admin-chosen slug identifier.
poll_status: object{ consecutive_failures, last_fetched_at, next_poll_at } or null
Status of automatic JWKS polling for a federation issuer.
Anthropic periodically fetches the issuer's signing keys in the background. These fields summarize the most recent fetches so the health of the JWKS endpoint can be monitored.
consecutive_failures: number
Consecutive fetch failures since the last success.
last_fetched_at: string or null
When the last successful fetch completed.
formatdate-time
next_poll_at: string or null
When the next fetch is scheduled. Null if paused.
formatdate-time
type: "federation_issuer"
defaultfederation_issuer
updated_at: string
When this issuer was last updated.
formatdate-time
updated_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
next_page: string or null
Opaque cursor for the next page, or null if no more results.
List Federation Issuers
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-federation-issuers-retrieve-dc1ff0e58a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Issuers](/docs/en/api/http/admin/federation_issuers)
# Get Federation Issuer
GET/v1/organizations/federation_issuers/{federation_issuer_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Retrieve a federation issuer by its ID (`fdis_...`).
##### Path parameters
federation_issuer_id: string
ID of the federation issuer.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
FederationIssuer object{ id, archived_at, archived_by_actor_id, 12 more }
Registered external OIDC identity provider.
Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.
Get Federation Issuer
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers/$FEDERATION_ISSUER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-federation-issuers-update-59b1f7bf0f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_issuers%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Create Federation Issuer
Get Federation Issuer
List Federation Issuers
Update Federation Issuer
Archive Federation Issuer
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Issuers](/docs/en/api/http/admin/federation_issuers)
# Update Federation Issuer
POST/v1/organizations/federation_issuers/{federation_issuer_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Partially update a federation issuer.
Setting `jwks` replaces the full JWKS shape at once. Archived issuers cannot be updated; this returns 400. Create a new issuer instead.
Updating an issuer that backs a rule with a scope outside `workspace:developer` or `workspace:inference` requires a Console session.
##### Path parameters
federation_issuer_id: string
ID of the federation issuer to update.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
check_jti: optional boolean or null
Whether the jwt-bearer exchange enforces JTI single-use (replay protection) for tokens from this issuer. Applies only to assertions carrying a `jti` claim; tokens without one are accepted without single-use enforcement.
issuer_url: optional string or null
Replaces the `iss` claim value to match against. For discovery-mode issuers without a `discovery_base`, this is also the URL Anthropic fetches the OIDC discovery document and signing keys from, so changing it repoints the JWKS source. Changing the issuer URL to a well-known shared platform is rejected while any live rule under this issuer would not constrain tenant identity.
minLength1
jwks: optional object{ type, ca_cert_pem, discovery_base } or object{ type, url, ca_cert_pem } or object{ keys, type } or null
Replaces the entire JWKS configuration.
One of the following:
Discovery object{ type, ca_cert_pem, discovery_base }
JWKS via the issuer's OIDC discovery document.
type: "discovery"
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
discovery_base: optional string or null
Set when the discovery URL differs from `issuer_url`.
ExplicitURL object{ type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
url: string
JWKS endpoint.
minLength1
ca_cert_pem: optional string or null
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
maxLength8192
Inline object{ keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
minItems1
type: "inline"
jwks_polling_disabled: optional boolean or null
Only `false` is accepted, to re-enable polling after the system pauses it. Polling is paused automatically; sending `true` is rejected.
max_jwt_lifetime_seconds: optional number or null
Maximum allowed iat→exp spread for assertions from this issuer (1-176400 seconds, i.e. up to 49h). Assertions must carry both `iat` and `exp`; a missing `iat` is rejected.
maximum176400
exclusiveMinimum0
name: optional string or null
Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
maxLength255
minLength1
##### Returns
FederationIssuer object{ id, archived_at, archived_by_actor_id, 12 more }
Registered external OIDC identity provider.
Records an external IdP the organization trusts for the RFC 7523 jwt-bearer grant. The `issuer_url` must match the JWT `iss` claim exactly.
Update Federation Issuer
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers/$FEDERATION_ISSUER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdis_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"check_jti": true,
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"issuer_url": "https://token.actions.githubusercontent.com",
"jwks": {
"type": "discovery",
"ca_cert_pem": "ca_cert_pem",
"discovery_base": "discovery_base"
},
"jwks_polling_disabled_at": "2019-12-27T18:11:19.117Z",
"max_jwt_lifetime_seconds": 0,
"name": "github-actions",
"poll_status": {
"consecutive_failures": 0,
"last_fetched_at": "2019-12-27T18:11:19.117Z",
"next_poll_at": "2019-12-27T18:11:19.117Z"
},
"type": "federation_issuer",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-federation-rules-archive-346209d84b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Farchive)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# Archive Federation Rule
POST/v1/organizations/federation_rules/{federation_rule_id}/archive
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Archive a federation rule.
Token exchange through this rule stops immediately. Idempotent; re-archiving returns the rule with its original `archived_at`. Archiving clears the rule's workspace targeting (`workspace_id` and `workspace_ids` are emptied). Tokens already minted before archive remain valid until they expire. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session.
##### Path parameters
federation_rule_id: string
ID of the federation rule to archive.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
FederationRule object{ id, applies_to_all_workspaces, archived_at, 17 more }
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.
Archive Federation Rule
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
---
## Admin/api-admin-federation-rules-create-0500c5ec91.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# Create Federation Rule
POST/v1/organizations/federation_rules
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Create a federation rule owned by your organization.
The referenced issuer and the target service account must already exist in the same organization; invalid references are rejected with a 400 error. The workspace reference is validated. Membership is not checked at rule creation: token exchange resolves a single enabled workspace per call and is rejected unless the target service account is a member of that workspace (it is implicitly a member of the default workspace). Rules on well-known shared issuers (GitHub Actions, GitLab, Buildkite, Terraform Cloud, Google) must constrain tenant identity via an identity-bearing claim, a tenant-pinning subject prefix (such as `repo:YOUR_ORG/...`), or a CEL condition referencing one of those identity claims (e.g. `claims.repository_owner`). OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
issuer_id: string
Tagged ID of the federation issuer.
match: object{ audience, claims, condition, subject_prefix }
Conditions the verified JWT must satisfy for this rule to apply. At least one of `subject_prefix` (other than a wildcard-only value like `*`), `claims`, or `condition` is required; `audience` alone is not sufficient.
audience: optional string or null
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.
maxLength1024
claims: optional map\[string\] or null
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
condition: optional string or null
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.
maxLength4096
subject_prefix: optional string or null
Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.
maxLength1024
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
maxLength255
minLength1
oauth_scope: string
Space-separated OAuth scopes. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session.
minLength1
target: object{ service_account_id, type, service_account_name }
Identity that tokens minted via this rule act as. Currently always a `service_account` target.
service_account_id: string
Tagged ID of the service account to mint tokens for.
type: "service_account"
service_account_name: optional string or null
Service account's display name at read time. Ignored on writes.
applies_to_all_workspaces: optional boolean
When true, enable this rule for every workspace in the org (including workspaces created later).
attributes: optional map\[string\] or null
CEL expressions `{name: expr}` extracting named values from claims. Not yet supported; any non-empty value is rejected with 400.
description: optional string or null
Optional free-text description.
maxLength2000
token_lifetime_seconds: optional number
Lifetime in seconds for access tokens minted via this rule (60-86400). Defaults to 3600 (1h). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
maximum86400
minimum60
workspace_id: optional string or null
Tagged ID of the workspace to enable this rule for. Required unless `applies_to_all_workspaces` is true. Additional workspaces can be added via the `/federation_rules/{federation_rule_id}/workspaces` sub-resource.
##### Returns
FederationRule object{ id, applies_to_all_workspaces, archived_at, 17 more }
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.
Create Federation Rule
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"issuer_id": "issuer_id",
"match": {},
"name": "x",
"oauth_scope": "x",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account"
}
}'
```
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
---
## Admin/api-admin-federation-rules-dbd00402df.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Federation Rules
##### [Create Federation Rule](/docs/en/api/http/admin/federation_rules/create)
POST/v1/organizations/federation_rules
##### [Get Federation Rule](/docs/en/api/http/admin/federation_rules/retrieve)
GET/v1/organizations/federation_rules/{federation_rule_id}
##### [List Federation Rules](/docs/en/api/http/admin/federation_rules/list)
GET/v1/organizations/federation_rules
##### [Update Federation Rule](/docs/en/api/http/admin/federation_rules/update)
POST/v1/organizations/federation_rules/{federation_rule_id}
##### [Archive Federation Rule](/docs/en/api/http/admin/federation_rules/archive)
POST/v1/organizations/federation_rules/{federation_rule_id}/archive
##### Models
FederationRule object{ id, applies_to_all_workspaces, archived_at, 17 more }
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.
#### Federation Rules[Workspaces](/docs/en/api/http/admin/federation_rules/workspaces)
##### [List Federation Rule Workspaces](/docs/en/api/http/admin/federation_rules/workspaces/list)
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Add Federation Rule Workspace](/docs/en/api/http/admin/federation_rules/workspaces/create)
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Remove Federation Rule Workspace](/docs/en/api/http/admin/federation_rules/workspaces/delete)
DELETE/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}
---
## Admin/api-admin-federation-rules-list-95f4176558.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# List Federation Rules
GET/v1/organizations/federation_rules
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List federation rules in your organization.
Optionally filter by issuer with `issuer_id`. Archived rules are excluded unless `include_archived=true`.
##### Query parameters
include_archived: optional boolean
Include archived resources. Defaults to false.
defaultfalse
issuer_id: optional string
Filter to rules referencing this federation issuer.
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of [FederationRule](/docs/en/api/http/admin/federation_rules#federation_rule) { id, applies_to_all_workspaces, archived_at, 17 more }
id: string
Tagged ID of the federation rule.
applies_to_all_workspaces: boolean
When true, this rule is enabled for every workspace in the org (including ones created after the rule). `workspace_ids` is ignored at exchange time.
archived_at: string or null
If set, this rule is archived and rejects token exchange.
formatdate-time
archived_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
attributes: map\[string\] or null
CEL expressions extracting named values from claims. Not yet supported; always null.
created_at: string
When this rule was created.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
description: string or null
Optional free-text description.
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
issuer_name: string or null
Issuer's display name at read time.
match: object{ audience, claims, condition, subject_prefix }
Conditions the verified JWT must satisfy for this rule to apply. All populated matcher fields must pass.
audience: optional string or null
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.
maxLength1024
claims: optional map\[string\] or null
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
condition: optional string or null
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.
maxLength4096
subject_prefix: optional string or null
Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.
maxLength1024
name: string
Admin-chosen slug identifier.
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
target: object{ service_account_id, type, service_account_name }
Identity that tokens minted via this rule act as. Currently always a `service_account` target.
service_account_id: string
Tagged ID of the service account to mint tokens for.
type: "service_account"
service_account_name: optional string or null
Service account's display name at read time. Ignored on writes.
token_lifetime_seconds: number
Lifetime in seconds of access tokens minted via this rule. Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
type: "federation_rule"
defaultfederation_rule
updated_at: string
When this rule was last updated.
formatdate-time
updated_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
workspace_id: string or null
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
workspace_ids: array of string
Tagged IDs of the workspaces this rule is enabled for. May be empty for older rules that only carry the legacy `workspace_id` binding. Ignored at exchange time when `applies_to_all_workspaces` is true (the list may still be non-empty).
next_page: string or null
Opaque cursor for the next page, or null if no more results.
List Federation Rules
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
---
## Admin/api-admin-federation-rules-retrieve-46fc0a0dc7.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# Get Federation Rule
GET/v1/organizations/federation_rules/{federation_rule_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Retrieve a federation rule by its ID (`fdrl_...`).
##### Path parameters
federation_rule_id: string
ID of the federation rule.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
FederationRule object{ id, applies_to_all_workspaces, archived_at, 17 more }
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.
Get Federation Rule
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
---
## Admin/api-admin-federation-rules-update-2413653e5a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# Update Federation Rule
POST/v1/organizations/federation_rules/{federation_rule_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Partially update a federation rule.
`issuer_id` is immutable. `match` and `target` are replaced as whole objects when set. Referenced service accounts and workspaces must exist in your organization; invalid references are rejected with a 400 error. Archived rules cannot be updated; this returns 400. Create a new rule instead. Rules on well-known shared issuers (GitHub Actions, GitLab, Buildkite, Terraform Cloud, Google) must constrain tenant identity via an identity-bearing claim, a tenant-pinning subject prefix (such as `repo:YOUR_ORG/...`), or a CEL condition referencing one of those identity claims (e.g. `claims.repository_owner`). On these issuers the requirement is re-checked on every update; if an existing rule's stored match does not yet constrain tenant identity, any update (even a rename or description change) must also supply a conforming `match` in the same request. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session.
##### Path parameters
federation_rule_id: string
ID of the federation rule to update.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
applies_to_all_workspaces: optional boolean or null
When true, enables this rule for every workspace in the org (including workspaces created later). Setting `false` is rejected with 400 if no workspace would remain enabled; a rule with only a legacy `workspace_id` binding continues to mint.
attributes: optional map\[string\] or null
Replaces the CEL expressions `{name: expr}` extracting named values from claims. Send null to clear them. Not yet supported; any non-empty value is rejected with 400.
description: optional string or null
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string).
maxLength2000
match: optional object{ audience, claims, condition, subject_prefix } or null
Does the incoming JWT qualify?
All populated fields must pass; omitted fields are skipped. At least one of `subject_prefix` (other than a wildcard-only value like `*`), `claims`, or `condition` is required; `audience` alone is not sufficient.
audience: optional string or null
Exact match against the `aud` claim (any element if array). When omitted, the JWT's `aud` must still equal Anthropic's expected audience for the issuer; setting this field overrides that default.
maxLength1024
claims: optional map\[string\] or null
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
condition: optional string or null
CEL expression over claims for logic the structural fields can't express. Must evaluate to a boolean and may reference only the `claims` variable; a constant-true expression (such as `true`) is rejected with 400.
maxLength4096
subject_prefix: optional string or null
Match the verified JWT `sub` claim. Exact match unless the value ends with `*`, in which case it is a prefix match. Example: `repo:my-org/my-repo:ref:refs/heads/main`.
maxLength1024
name: optional string or null
Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
maxLength255
minLength1
oauth_scope: optional string or null
Replaces the space-separated OAuth scopes granted on minted tokens. OAuth callers may only set `workspace:developer` or `workspace:inference`; other scopes (such as `org:admin`) require a Console session.
minLength1
target: optional object{ service_account_id, type, service_account_name } or null
Bind to a fixed service account by ID.
service_account_id: string
Tagged ID of the service account to mint tokens for.
type: "service_account"
service_account_name: optional string or null
Service account's display name at read time. Ignored on writes.
token_lifetime_seconds: optional number or null
Replaces the lifetime in seconds for access tokens minted via this rule (60-86400). Minted tokens are capped at `max(60, min(this value, 2 × remaining assertion validity))` seconds.
maximum86400
minimum60
workspace_id: optional string or null
Replaces the existing single workspace enablement (the previous one is removed). Rejected with 400 if the rule is enabled for more than one workspace; use the `/federation_rules/{federation_rule_id}/workspaces` sub-resource instead.
##### Returns
FederationRule object{ id, applies_to_all_workspaces, archived_at, 17 more }
Authorization rule binding an external OIDC identity to Anthropic.
Evaluates the match conditions and mints an OAuth access token for the resolved target, scoped to a single workspace where the rule is enabled (chosen by the caller at exchange time when the rule is enabled for more than one). For rules enabled via `workspace_ids` or `applies_to_all_workspaces`, the target service account must be a member of that workspace (it is implicitly a member of the default workspace); rules carrying only the legacy `workspace_id` binding do not enforce this.
Update Federation Rule
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
"workspace_ids": [
"string"
]
}
```
##### Returns Examples
Response 200
```python
{
"id": "fdrl_01SDCCSbTxrXDpWc1phhtcfK",
"applies_to_all_workspaces": true,
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"attributes": {
"foo": "string"
},
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"issuer_id": "issuer_id",
"issuer_name": "issuer_name",
"match": {
"audience": "audience",
"claims": {
"foo": "string"
},
"condition": "condition",
"subject_prefix": "subject_prefix"
},
"name": "prod-deploy-pipeline",
"oauth_scope": "oauth_scope",
"target": {
"service_account_id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"type": "service_account",
"service_account_name": "service_account_name"
},
"token_lifetime_seconds": 0,
"type": "federation_rule",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id",
"workspace_id": "workspace_id",
---
## Admin/api-admin-federation-rules-workspaces-9e2a1c5268.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fworkspaces)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
List Federation Rule Workspaces
Add Federation Rule Workspace
Remove Federation Rule Workspace
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
# Workspaces
##### [List Federation Rule Workspaces](/docs/en/api/http/admin/federation_rules/workspaces/list)
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Add Federation Rule Workspace](/docs/en/api/http/admin/federation_rules/workspaces/create)
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Remove Federation Rule Workspace](/docs/en/api/http/admin/federation_rules/workspaces/delete)
DELETE/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}
##### Models
WorkspaceCreateResponse object{ created_at, created_by_actor_id, federation_rule_id, 3 more }
created_at: string
When this workspace was enabled for the rule.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace"
defaultfederation_rule_workspace
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
workspace_name: string or null
Workspace display name. Populated when listing; null in the enable response.
WorkspaceListResponse object{ created_at, created_by_actor_id, federation_rule_id, 3 more }
created_at: string
When this workspace was enabled for the rule.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace"
defaultfederation_rule_workspace
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
workspace_name: string or null
Workspace display name. Populated when listing; null in the enable response.
WorkspaceDeleteResponse object{ federation_rule_id, type, workspace_id }
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace_deleted"
defaultfederation_rule_workspace_deleted
workspace_id: string
Tagged ID of the workspace named in the delete request. Removal is idempotent.
---
## Admin/api-admin-federation-rules-workspaces-create-42e176bc37.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fworkspaces%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
List Federation Rule Workspaces
Add Federation Rule Workspace
Remove Federation Rule Workspace
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
4. [Workspaces](/docs/en/api/http/admin/federation_rules/workspaces)
# Add Federation Rule Workspace
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Enable a federation rule for a workspace.
Idempotent; re-enabling returns the existing enablement. The rule and workspace must both belong to your organization. Membership of the rule's target service account in this workspace is not checked at enablement: token exchange into this workspace is rejected unless the target is a member (it is implicitly a member of the default workspace). Archived rules are rejected with 400. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session.
##### Path parameters
federation_rule_id: string
ID of the federation rule.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
workspace_id: string
Tagged ID of the workspace to enable this rule for.
##### Returns
created_at: string
When this workspace was enabled for the rule.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace"
defaultfederation_rule_workspace
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
workspace_name: string or null
Workspace display name. Populated when listing; null in the enable response.
Add Federation Rule Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"workspace_id": "workspace_id"
}'
```
Response 200
```python
{
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace",
"workspace_id": "workspace_id",
"workspace_name": "workspace_name"
}
```
##### Returns Examples
Response 200
```python
{
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace",
"workspace_id": "workspace_id",
"workspace_name": "workspace_name"
---
## Admin/api-admin-federation-rules-workspaces-delete-59582bb311.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fworkspaces%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
List Federation Rule Workspaces
Add Federation Rule Workspace
Remove Federation Rule Workspace
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
4. [Workspaces](/docs/en/api/http/admin/federation_rules/workspaces)
# Remove Federation Rule Workspace
DELETE/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Disable a federation rule for a workspace.
Idempotent; succeeds even if the enablement was already removed. OAuth callers may only manage rules whose `oauth_scope` is `workspace:developer` or `workspace:inference`; other scopes require a Console session.
##### Path parameters
federation_rule_id: string
ID of the federation rule.
workspace_id: string
ID of the workspace to disable for.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace_deleted"
defaultfederation_rule_workspace_deleted
workspace_id: string
Tagged ID of the workspace named in the delete request. Removal is idempotent.
Remove Federation Rule Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID/workspaces/$WORKSPACE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace_deleted",
"workspace_id": "workspace_id"
}
```
##### Returns Examples
Response 200
```python
{
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace_deleted",
"workspace_id": "workspace_id"
---
## Admin/api-admin-federation-rules-workspaces-list-f756b6bc09.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Ffederation_rules%2Fworkspaces%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
Create Federation Rule
Get Federation Rule
List Federation Rules
Update Federation Rule
Archive Federation Rule
Workspaces
List Federation Rule Workspaces
Add Federation Rule Workspace
Remove Federation Rule Workspace
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Federation Rules](/docs/en/api/http/admin/federation_rules)
4. [Workspaces](/docs/en/api/http/admin/federation_rules/workspaces)
# List Federation Rule Workspaces
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List workspaces where this federation rule is enabled.
Returns all workspace enablements in a single response; the `limit` and `page` parameters are accepted but have no effect, and `next_page` is always `null`. Returns explicit per-workspace enablements only; for rules with `applies_to_all_workspaces` or a legacy single `workspace_id`, check those fields on the rule itself.
##### Path parameters
federation_rule_id: string
ID of the federation rule.
##### Query parameters
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of object{ created_at, created_by_actor_id, federation_rule_id, 3 more }
created_at: string
When this workspace was enabled for the rule.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
federation_rule_id: string
Tagged ID of the federation rule.
type: "federation_rule_workspace"
defaultfederation_rule_workspace
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
workspace_name: string or null
Workspace display name. Populated when listing; null in the enable response.
next_page: string or null
Opaque cursor for the next page; null when there are no more results.
List Federation Rule Workspaces
cURL
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace",
"workspace_id": "workspace_id",
"workspace_name": "workspace_name"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"federation_rule_id": "federation_rule_id",
"type": "federation_rule_workspace",
"workspace_id": "workspace_id",
"workspace_name": "workspace_name"
---
## Admin/api-admin-invites-c6a7bd3b33.md
# Invites
## Create
**post** `/v1/organizations/invites`
Create Invite
### Body Parameters
- `email: string`
Email of the User.
- `role: "user" or "developer" or "billing" or "claude_code_user"`
Role for the invited User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"email": "user@emaildomain.com",
"role": "user"
}'
```
## Retrieve
**get** `/v1/organizations/invites/{invite_id}`
Get Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/invites`
List Invites
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Invite`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Delete
**delete** `/v1/organizations/invites/{invite_id}`
Delete Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Invite
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Invite Delete Response
- `InviteDeleteResponse = object { id, type }`
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
---
## Admin/api-admin-invites-create-4e7f9221ab.md
## Create
**post** `/v1/organizations/invites`
Create Invite
### Body Parameters
- `email: string`
Email of the User.
- `role: "user" or "developer" or "billing" or "claude_code_user"`
Role for the invited User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"email": "user@emaildomain.com",
"role": "user"
}'
```
---
## Admin/api-admin-invites-create-ddbb63dd41.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Finvites%2Fcreate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Create Invite
List Invites
Get Invite
Delete Invite
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Invites](/docs/en/api/http/beta/organization/invites)
# Create Invite
POST/v1/organizations/invites
Invite a user to join the organization by email.
On plans that draw members from a finite pool of purchased seats, the invite automatically consumes a seat from the lowest tier with availability; there is no seat-tier parameter. When no seat is free the request fails with a 400 error rather than purchasing a seat.
##### Body
email: string
Email of the User.
formatemail
role: "billing" or "claude_code_user" or "developer" or 2 more
Role for the invited User.
The accepted values depend on the organization type. Console and API organizations accept `user`, `developer`, `billing`, and `claude_code_user`; `admin` cannot be assigned through the API. Claude Enterprise organizations accept `user` and `managed`.
One of the following:
"billing"
"claude_code_user"
"developer"
"managed"
"user"
rbac_group_ids: optional array of string
RBAC group IDs to assign to the User when the Invite is accepted. A non-empty array is accepted only for a Claude Enterprise organization with RBAC groups, and requires the key to carry the `write:rbac_groups` scope.
maxItems100
##### Returns
BetaOrganizationInvite object{ type: "invite", id, accepted_at, 6 more }
Create Invite
cURL
```python
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-d '{
"email": "user@emaildomain.com",
"role": "user"
}'
```
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
"rbac_group_ids": [
"string"
],
"role": "admin",
"status": "pending",
"type": "invite"
}
```
##### Returns Examples
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
---
## Admin/api-admin-invites-delete-4d77b687fd.md
## Delete
**delete** `/v1/organizations/invites/{invite_id}`
Delete Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `id: string`
ID of the Invite.
- `type: "invite_deleted"`
Deleted object type.
For Invites, this is always `"invite_deleted"`.
- `"invite_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-delete-8b66256d2e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Finvites%2Fdelete)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Create Invite
List Invites
Get Invite
Delete Invite
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Invites](/docs/en/api/http/beta/organization/invites)
# Delete Invite
DELETE/v1/organizations/invites/{invite_id}
Delete a pending invite.
##### Path parameters
invite_id: string
ID of the Invite.
##### Returns
type: "invite_deleted"
Deleted object type.
For Invites, this is always `"invite_deleted"`.
defaultinvite_deleted
id: string
ID of the Invite.
Delete Invite
cURL
```python
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"type": "invite_deleted"
}
```
##### Returns Examples
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
---
## Admin/api-admin-invites-ee5daa080d.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Finvites)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Create Invite
Get Invite
List Invites
Delete Invite
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Invites
##### [Create Invite](/docs/en/api/http/admin/invites/create)
POST/v1/organizations/invites
##### [Get Invite](/docs/en/api/http/admin/invites/retrieve)
GET/v1/organizations/invites/{invite_id}
##### [List Invites](/docs/en/api/http/admin/invites/list)
GET/v1/organizations/invites
##### [Delete Invite](/docs/en/api/http/admin/invites/delete)
DELETE/v1/organizations/invites/{invite_id}
##### Models
Invite object{ id, accepted_at, email, 6 more }
InviteDeleteResponse object{ id, type }
id: string
ID of the Invite.
type: "invite_deleted"
Deleted object type.
For Invites, this is always `"invite_deleted"`.
---
## Admin/api-admin-invites-list-d4f19c73c1.md
## List
**get** `/v1/organizations/invites`
List Invites
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Invite`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-list-e1104b560e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Finvites%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Create Invite
List Invites
Get Invite
Delete Invite
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Invites](/docs/en/api/http/beta/organization/invites)
# List Invites
GET/v1/organizations/invites
List the organization's invites.
##### Query parameters
after_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
email: optional string
Filter by the email address the Invite was sent to. Matches the same way as the Users list's `email` filter (normalized, case-insensitive).
formatemail
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
roles: optional array of string
Filter to items whose `role` equals one of the supplied values. Repeatable; values are OR'ed together.
Accepted values depend on the organization type: Console and API organizations accept `user`, `developer`, `billing`, `admin`, and `claude_code_user`; Claude Enterprise organizations accept `user`, `owner`, `primary_owner`, `membership_admin`, and `managed`.
statuses: optional array of "accepted" or "expired" or "pending"
Filter by Invite status. Repeatable; values are OR'ed together. Omit to return `pending`, `accepted`, and `expired` Invites alike.
One of the following:
"accepted"
"expired"
"pending"
##### Returns
data: array of [BetaOrganizationInvite](/docs/en/api/http/beta/organization/invites#beta_organization_invite) { type: "invite", id, accepted_at, 6 more }
type: "invite"
Object type.
For Invites, this is always `"invite"`.
defaultinvite
id: string
ID of the Invite.
accepted_at: string or null
RFC 3339 datetime string indicating when the Invite was accepted, or null.
formatdate-time
email: string
Email of the User being invited.
expires_at: string
RFC 3339 datetime string indicating when the Invite expires.
formatdate-time
invited_at: string
RFC 3339 datetime string indicating when the Invite was created.
formatdate-time
rbac_group_ids: array of string
RBAC group IDs recorded on the Invite (Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none.
role: [BetaOrganizationRole](/docs/en/api/http/beta/organization#beta_organization_role)
Organization role of the User.
One of the following:
"admin"
"billing"
"claude_code_user"
"developer"
"managed"
"membership_admin"
"owner"
"primary_owner"
"user"
status: "accepted" or "deleted" or "expired" or "pending"
Status of the Invite.
One of the following:
"accepted"
"deleted"
"expired"
"pending"
first_id: string or null
First ID in the `data` list. Can be used as the `before_id` for the previous page.
has_more: boolean
Indicates if there are more results in the requested page direction.
last_id: string or null
Last ID in the `data` list. Can be used as the `after_id` for the next page.
List Invites
cURL
```python
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
"rbac_group_ids": [
"string"
],
"role": "admin",
"status": "pending",
"type": "invite"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
---
## Admin/api-admin-invites-retrieve-07968dba44.md
## Retrieve
**get** `/v1/organizations/invites/{invite_id}`
Get Invite
### Path Parameters
- `invite_id: string`
ID of the Invite.
### Returns
- `Invite = object { id, email, expires_at, 4 more }`
- `id: string`
ID of the Invite.
- `email: string`
Email of the User being invited.
- `expires_at: string`
RFC 3339 datetime string indicating when the Invite expires.
- `invited_at: string`
RFC 3339 datetime string indicating when the Invite was created.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `status: "accepted" or "expired" or "deleted" or "pending"`
Status of the Invite.
- `"accepted"`
- `"expired"`
- `"deleted"`
- `"pending"`
- `type: "invite"`
Object type.
For Invites, this is always `"invite"`.
- `"invite"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-invites-retrieve-0be0a2e6ea.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Finvites%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Create Invite
List Invites
Get Invite
Delete Invite
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Invites](/docs/en/api/http/beta/organization/invites)
# Get Invite
GET/v1/organizations/invites/{invite_id}
Retrieve an invite by ID.
##### Path parameters
invite_id: string
ID of the Invite.
##### Returns
BetaOrganizationInvite object{ type: "invite", id, accepted_at, 6 more }
Get Invite
cURL
```python
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
"rbac_group_ids": [
"string"
],
"role": "admin",
"status": "pending",
"type": "invite"
}
```
##### Returns Examples
Response 200
```python
{
"id": "invite_015gWxCN9Hfg2QhZwTK7Mdeu",
"accepted_at": "2019-12-27T18:11:19.117Z",
"email": "user@emaildomain.com",
"expires_at": "2024-11-20T23:58:27.427722Z",
"invited_at": "2024-10-30T23:58:27.427722Z",
---
## Admin/api-admin-mcp-tunnels-archive-127a2366d0.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Farchive)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# Archive Tunnel
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/archive
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Archive a tunnel. Archival is irreversible.
Every non-archived certificate on the tunnel is archived in the same operation, the hostname is retired and never re-allocated, and the tunnel token is invalidated. Retrying against an already-archived tunnel returns the existing record unchanged.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
Archive Tunnel
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
```
##### Returns Examples
Response 200
```python
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-mcp-tunnels-f9e9a2a9d4.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# MCP Tunnels
##### [Get Tunnel](/docs/en/api/http/admin/mcp_tunnels/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}
##### [List Tunnels](/docs/en/api/http/admin/mcp_tunnels/list)
Deprecated
GET/v1/organizations/tunnels
##### [Reveal Tunnel Token](/docs/en/api/http/admin/mcp_tunnels/reveal_token)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/reveal_token
##### [Rotate Tunnel Token](/docs/en/api/http/admin/mcp_tunnels/rotate_token)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/rotate_token
##### [Archive Tunnel](/docs/en/api/http/admin/mcp_tunnels/archive)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/archive
##### Models
MCPTunnelRetrieveResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
MCPTunnelListResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
MCPTunnelArchiveResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
MCPTunnelRevealTokenResponse object{ id, tunnel_token, type }
id: string
Stable identifier for the current token value. Changes when the token is rotated.
tunnel_token: string
The tunnel's connection token.
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
defaulttunnel_token
MCPTunnelRotateTokenResponse object{ id, tunnel_token, type }
id: string
Stable identifier for the current token value. Changes when the token is rotated.
tunnel_token: string
The tunnel's connection token.
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
defaulttunnel_token
#### MCP Tunnels[Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates)
##### [Create Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/create)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Get Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
##### [List Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/list)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Archive Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/archive)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive
---
## Admin/api-admin-mcp-tunnels-list-f1751a97b3.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# List Tunnels
Deprecated
GET/v1/organizations/tunnels
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
List the organization's tunnels.
Results span the caller's organization, ordered by creation time (newest first). Use `workspace_id` to filter to a single workspace; archived tunnels are excluded unless `include_archived` is set.
##### Query parameters
include_archived: optional boolean
Include archived tunnels in the results. Archived tunnels are excluded by default.
defaultfalse
limit: optional number
Maximum number of tunnels to return in a single page.
default20
maximum1000
minimum1
page: optional string
Opaque pagination cursor from a previous response's `next_page`. Omit to fetch the first page.
workspace_id: optional string
Return only tunnels in this Workspace. Accepts a `wrkspc_`-prefixed Workspace ID; omit to list tunnels across all Workspaces.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
data: array of object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
next_page: string or null
Opaque cursor for the next page, or `null` if there are no more results.
List Tunnels
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
---
## Admin/api-admin-mcp-tunnels-retrieve-c85b2f950e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# Get Tunnel
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Retrieve a single tunnel in the caller's organization by ID.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
id: string
ID of the Tunnel.
archived_at: string or null
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
formatdate-time
display_name: string or null
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
domain: string
Anthropic-assigned hostname for the Tunnel. MCP server URLs whose host is a subdomain of this value are routed through the Tunnel. Globally unique and never reused, even after the Tunnel is archived.
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
defaulttunnel
workspace_id: string or null
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
Get Tunnel
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
```
##### Returns Examples
Response 200
```python
{
"id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"display_name": "Production",
"domain": "a1b2c3d4.tunnel.anthropic.com",
"type": "tunnel",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-mcp-tunnels-reveal-token-35f21ba902.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Freveal_token)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# Reveal Tunnel Token
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/reveal_token
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Return the tunnel's current connection token.
The value is fetched live on each call; Anthropic does not store it. Repeated calls return the same value until the token is rotated. Exposed as `POST` so the token does not appear in intermediary access logs.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
id: string
Stable identifier for the current token value. Changes when the token is rotated.
tunnel_token: string
The tunnel's connection token.
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
defaulttunnel_token
Reveal Tunnel Token
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/reveal_token \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
"type": "tunnel_token"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
---
## Admin/api-admin-mcp-tunnels-rotate-token-d0e3cad1c8.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Frotate_token)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# Rotate Tunnel Token
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/rotate_token
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Invalidate the tunnel's current token for new connections and return a fresh value.
Established connections are not severed by rotation; a connector restarted after rotation must use the new value. An optional `reason` is captured for operational context.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Body
reason: optional string or null
Optional free-text reason for the rotation, recorded for audit.
maxLength1024
##### Returns
id: string
Stable identifier for the current token value. Changes when the token is rotated.
tunnel_token: string
The tunnel's connection token.
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
defaulttunnel_token
Rotate Tunnel Token
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/rotate_token \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
"type": "tunnel_token"
}
```
##### Returns Examples
Response 200
```python
{
"id": "ttkn_bb97000eaec162831399ca9b6684a4fdf5be49ace5683057b017aab5c87e19e0",
"tunnel_token": "eyJhIjoiRVhBTVBMRSIsInQiOiJFWEFNUExFIiwicyI6IkVYQU1QTEUifQ==",
---
## Admin/api-admin-mcp-tunnels-tunnel-certificates-59dafa8cbd.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Ftunnel_certificates)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Create Tunnel Certificate
Get Tunnel Certificate
List Tunnel Certificates
Archive Tunnel Certificate
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
# Tunnel Certificates
##### [Create Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/create)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Get Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
##### [List Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/list)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Archive Tunnel Certificate](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates/archive)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive
##### Models
TunnelCertificateCreateResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
TunnelCertificateRetrieveResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
TunnelCertificateListResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
TunnelCertificateArchiveResponse object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
---
## Admin/api-admin-mcp-tunnels-tunnel-certificates-archive-3672e7c198.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Ftunnel_certificates%2Farchive)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Create Tunnel Certificate
Get Tunnel Certificate
List Tunnel Certificates
Archive Tunnel Certificate
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
4. [Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates)
# Archive Tunnel Certificate
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Archive a certificate, removing it from the set Anthropic trusts for this tunnel.
The certificate record is retained. Archiving the last non-archived certificate is permitted; the tunnel rejects MCP traffic until a new certificate is added.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
certificate_id: string
ID of the Tunnel Certificate.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
Archive Tunnel Certificate
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
```
##### Returns Examples
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
---
## Admin/api-admin-mcp-tunnels-tunnel-certificates-create-a681df2265.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Ftunnel_certificates%2Fcreate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Create Tunnel Certificate
Get Tunnel Certificate
List Tunnel Certificates
Archive Tunnel Certificate
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
4. [Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates)
# Create Tunnel Certificate
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Register a public CA certificate for the tunnel.
Anthropic verifies the gateway's server certificate against this CA when it terminates the inner TLS session. The PEM body must contain exactly one X.509 certificate and no private-key material. A tunnel holds at most two non-archived certificates.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Body
ca_certificate_pem: string
PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material.
maxLength8192
##### Returns
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
Create Tunnel Certificate
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"ca_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIBexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexampleEXAMPLEexa\n...illustrative placeholder, not a real certificate...\n-----END CERTIFICATE-----\n"
}'
```
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
```
##### Returns Examples
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
---
## Admin/api-admin-mcp-tunnels-tunnel-certificates-list-1fafa324ee.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Ftunnel_certificates%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Create Tunnel Certificate
Get Tunnel Certificate
List Tunnel Certificates
Archive Tunnel Certificate
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
4. [Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates)
# List Tunnel Certificates
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
List the certificates registered on a tunnel.
Archived certificates are excluded unless `include_archived` is set.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
##### Query parameters
include_archived: optional boolean
Include archived certificates in the results. Archived certificates are excluded by default.
defaultfalse
limit: optional number
Maximum number of certificates to return.
default20
maximum1000
minimum1
page: optional string
A tunnel has at most two active certificates, so this list is not paginated.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
data: array of object{ id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
next_page: string or null
Opaque cursor for the next page, or `null` if there are no more results.
List Tunnel Certificates
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
],
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
---
## Admin/api-admin-mcp-tunnels-tunnel-certificates-retrieve-f439f3bcc8.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fmcp_tunnels%2Ftunnel_certificates%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Get Tunnel
List Tunnels
Reveal Tunnel Token
Rotate Tunnel Token
Archive Tunnel
Tunnel Certificates
Create Tunnel Certificate
Get Tunnel Certificate
List Tunnel Certificates
Archive Tunnel Certificate
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [MCP Tunnels](/docs/en/api/http/admin/mcp_tunnels)
4. [Tunnel Certificates](/docs/en/api/http/admin/mcp_tunnels/tunnel_certificates)
# Get Tunnel Certificate
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
**Deprecated.** This Admin API endpoint is superseded by `/v1/tunnels` on the Claude API and will be removed after a migration window. New integrations should use [`/v1/tunnels`](/docs/en/api/beta/tunnels) with the `anthropic-beta: mcp-tunnels-2026-06-22` header and a WIF token carrying the `workspace:manage_tunnels` scope. Existing integrations continue to work with the `mcp-tunnels-2026-05-19` header and `org:manage_tunnels` scope during the migration window.
Retrieve a single certificate registered on a tunnel by ID.
##### Path parameters
tunnel_id: string
ID of the Tunnel.
certificate_id: string
ID of the Tunnel Certificate.
##### Headers
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
##### Returns
id: string
ID of the Tunnel Certificate.
archived_at: string or null
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
formatdate-time
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
formatdate-time
expires_at: string or null
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
formatdate-time
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
tunnel_id: string
ID of the Tunnel this certificate is registered against.
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
defaulttunnel_certificate
Get Tunnel Certificate
cURL
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
"type": "tunnel_certificate"
}
```
##### Returns Examples
Response 200
```python
{
"id": "tcrt_01JmWq4ZxnBvR7tKpY2sLdH9",
"archived_at": "2024-11-01T23:59:27.427722Z",
"created_at": "2024-10-30T23:58:27.427722Z",
"expires_at": "2024-10-30T23:58:27.427722Z",
"fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"tunnel_id": "tnl_01Hx9Kp2RtQvMn3sWbYdLcF8",
---
## Admin/api-admin-organizations-2429119ffe.md
# Organizations
## Me
**get** `/v1/organizations/me`
Retrieve information about the organization associated with the authenticated API key.
### Returns
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Organization
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
---
## Admin/api-admin-organizations-c021cbef11.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Forganizations)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Get Current Organization
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Organizations
##### [Get Current Organization](/docs/en/api/http/admin/organizations/me)
GET/v1/organizations/me
##### Models
Organization object{ id, name, type }
id: string
ID of the Organization.
formatuuid
name: string
Name of the Organization.
type: "organization"
Object type.
For Organizations, this is always `"organization"`.
---
## Admin/api-admin-organizations-me-85ca0a0bba.md
## Me
**get** `/v1/organizations/me`
Retrieve information about the organization associated with the authenticated API key.
### Returns
- `Organization = object { id, name, type }`
- `id: string`
ID of the Organization.
- `name: string`
Name of the Organization.
- `type: "organization"`
Object type.
For Organizations, this is always `"organization"`.
- `"organization"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-organizations-me-d9e732cac8.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Forganizations%2Fme)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Get Current Organization
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Organizations](/docs/en/api/http/admin/organizations)
# Get Current Organization
GET/v1/organizations/me
Retrieve information about the organization associated with the authenticated API key.
##### Returns
Organization object{ id, name, type }
id: string
ID of the Organization.
formatuuid
name: string
Name of the Organization.
type: "organization"
Object type.
For Organizations, this is always `"organization"`.
defaultorganization
Get Current Organization
cURL
```python
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "12345678-1234-5678-1234-567812345678",
"name": "Organization Name",
"type": "organization"
}
```
##### Returns Examples
Response 200
```python
{
"id": "12345678-1234-5678-1234-567812345678",
---
## Admin/api-admin-rate-limits-1ff96f3780.md
# Rate Limits
## List
**get** `/v1/organizations/rate_limits`
List Messages API rate limits for your organization.
Each entry corresponds to one rate-limit group (either a model family
or an API-surface category such as the Files API or Message Batches)
and contains the set of limiter values that apply to it.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `model: optional string`
Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization.
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-rate-limits-614f446d84.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frate_limits)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
List Organization Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Rate Limits
##### [List Organization Rate Limits](/docs/en/api/http/admin/rate_limits/list)
GET/v1/organizations/rate_limits
##### Models
RateLimitListResponse object{ id, group_type, limits, 2 more }
---
## Admin/api-admin-rate-limits-list-79cd935c72.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frate_limits%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
List Organization Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Rate Limits](/docs/en/api/http/admin/rate_limits)
# List Organization Rate Limits
GET/v1/organizations/rate_limits
List Messages API rate limits for your organization.
Each entry corresponds to one rate-limit group (either a model family or an API-surface category such as the Files API or Message Batches) and contains the set of limiter values that apply to it.
When `limit` is omitted, every matching entry is returned in a single page; when `limit` truncates the result, follow `next_page` to fetch the remaining entries.
##### Query parameters
group_type: optional "batch" or "files" or "model_group" or 3 more
Filter by group type.
One of the following:
"batch"
"files"
"model_group"
"skills"
"token_count"
"web_search"
limit: optional number
Maximum number of items to return per page. Ranges from `1` to `1000`.
When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
maximum1000
minimum1
model: optional string
Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization.
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Returns
data: array of object{ id, group_type, limits, 2 more }
Rate-limit entries for the organization, one per group.
id: string
Stable identifier for this rate-limit group within the organization.
group_type: "batch" or "files" or "model_group" or 3 more
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
One of the following:
"batch"
"files"
"model_group"
"skills"
"token_count"
"web_search"
limits: array of object{ type, value }
The limiter values that apply to this group.
type: string
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
value: number
The configured limit value for this limiter type.
models: array of string or null
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
type: "rate_limit"
Object type. Always `rate_limit` for organization rate-limit entries.
defaultrate_limit
next_page: string or null
Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
List Organization Rate Limits
cURL
```python
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
---
## Admin/api-admin-rate-limits-list-83d9e8ee16.md
## List
**get** `/v1/organizations/rate_limits`
List Messages API rate limits for your organization.
Each entry corresponds to one rate-limit group (either a model family
or an API-surface category such as the Files API or Message Batches)
and contains the set of limiter values that apply to it.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `model: optional string`
Filter to the single entry containing this model. Accepts full model names and aliases. Returns 404 if the model is not found or has no rate limits for this organization.
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the organization, one per group.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { type, value }`
The limiter values that apply to this group.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The configured limit value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "rate_limit"`
Object type. Always `rate_limit` for organization rate-limit entries.
- `"rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-rbac-groups-c37482379b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frbac_groups)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# RBAC Groups
##### [List RBAC Groups](/docs/en/api/http/admin/rbac_groups/list)
GET/v1/organizations/rbac_groups
##### [Get RBAC Group](/docs/en/api/http/admin/rbac_groups/retrieve)
GET/v1/organizations/rbac_groups/{group_id}
##### [Create RBAC Group](/docs/en/api/http/admin/rbac_groups/create)
POST/v1/organizations/rbac_groups
##### [Update RBAC Group](/docs/en/api/http/admin/rbac_groups/update)
POST/v1/organizations/rbac_groups/{group_id}
##### [Delete RBAC Group](/docs/en/api/http/admin/rbac_groups/delete)
DELETE/v1/organizations/rbac_groups/{group_id}
##### Models
RbacGroup object{ id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
formatdate-time
name: string
Name of the RBAC Group. Not uniqueness-enforced.
roles: array of string or null
RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list.
source_type: "direct" or "scim"
How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider.
One of the following:
"direct"
"scim"
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
defaultrbac_group
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
formatdate-time
RbacGroupDeleted object{ id, type }
id: string
ID of the RBAC Group.
type: "rbac_group_deleted"
Deleted object type.
For RBAC Groups, this is always `"rbac_group_deleted"`.
defaultrbac_group_deleted
#### RBAC Groups[Members](/docs/en/api/http/admin/rbac_groups/members)
##### [List RBAC Group Members](/docs/en/api/http/admin/rbac_groups/members/list)
GET/v1/organizations/rbac_groups/{group_id}/members
##### [Add RBAC Group Member](/docs/en/api/http/admin/rbac_groups/members/create)
POST/v1/organizations/rbac_groups/{group_id}/members
##### [Remove RBAC Group Member](/docs/en/api/http/admin/rbac_groups/members/delete)
DELETE/v1/organizations/rbac_groups/{group_id}/members/{user_id}
---
## Admin/api-admin-rbac-groups-create-ccdb836389.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fcreate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
# Create RBAC Group
POST/v1/organizations/rbac_groups
Create an RBAC Group in the Claude Enterprise tenant. Groups created via the API have source type `"direct"`.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Body
name: string
Name of the RBAC Group. Not uniqueness-enforced.
maxLength255
minLength1
##### Returns
BetaRBACGroup object{ type: "rbac_group", id, created_at, 4 more }
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
defaultrbac_group
id: string
ID of the RBAC Group.
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
formatdate-time
name: string
Name of the RBAC Group. Not uniqueness-enforced.
roles: array of string or null
RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list.
source_type: "direct" or "scim"
How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider.
One of the following:
"direct"
"scim"
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
formatdate-time
Create RBAC Group
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-d '{
"name": "Engineering"
}'
```
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-rbac-groups-delete-0a178f72c6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fdelete)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
# Delete RBAC Group
DELETE/v1/organizations/rbac_groups/{group_id}
Delete an RBAC Group. Groups provisioned by an identity provider (source type `"scim"`) cannot be deleted via the API while an organization in the tenant uses SCIM provisioning.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
##### Returns
BetaRBACGroupDeleted object{ type: "rbac_group_deleted", id }
type: "rbac_group_deleted"
Deleted object type.
For RBAC Groups, this is always `"rbac_group_deleted"`.
defaultrbac_group_deleted
id: string
ID of the RBAC Group.
Delete RBAC Group
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_deleted"
}
```
##### Returns Examples
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
---
## Admin/api-admin-rbac-groups-list-92526d58d5.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
# List RBAC Groups
GET/v1/organizations/rbac_groups
List RBAC Groups in the Claude Enterprise tenant.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Query parameters
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
page: optional string
Optionally set to the `next_page` token from the previous response.
##### Returns
data: array of [BetaRBACGroup](/docs/en/api/http/beta/organization/rbac_groups#beta_rbac_group) { type: "rbac_group", id, created_at, 4 more }
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
defaultrbac_group
id: string
ID of the RBAC Group.
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
formatdate-time
name: string
Name of the RBAC Group. Not uniqueness-enforced.
roles: array of string or null
RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list.
source_type: "direct" or "scim"
How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider.
One of the following:
"direct"
"scim"
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
formatdate-time
has_more: boolean
Indicates if there are more results in the requested page direction.
next_page: string or null
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
List RBAC Groups
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
],
"has_more": false,
"next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
],
"has_more": false,
"next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9"
---
## Admin/api-admin-rbac-groups-members-88f6f9853e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frbac_groups%2Fmembers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
List RBAC Group Members
Add RBAC Group Member
Remove RBAC Group Member
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [RBAC Groups](/docs/en/api/http/admin/rbac_groups)
# Members
##### [List RBAC Group Members](/docs/en/api/http/admin/rbac_groups/members/list)
GET/v1/organizations/rbac_groups/{group_id}/members
##### [Add RBAC Group Member](/docs/en/api/http/admin/rbac_groups/members/create)
POST/v1/organizations/rbac_groups/{group_id}/members
##### [Remove RBAC Group Member](/docs/en/api/http/admin/rbac_groups/members/delete)
DELETE/v1/organizations/rbac_groups/{group_id}/members/{user_id}
##### Models
RbacGroupMember object{ created_at, email, group_id, 2 more }
created_at: string
RFC 3339 timestamp of when the User was added to the RBAC Group.
formatdate-time
email: string
Email of the User.
group_id: string
ID of the RBAC Group.
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
defaultrbac_group_member
user_id: string
ID of the User.
RbacGroupMemberDeleted object{ group_id, type, user_id }
group_id: string
ID of the RBAC Group.
type: "rbac_group_member_deleted"
Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`.
defaultrbac_group_member_deleted
user_id: string
ID of the User.
---
## Admin/api-admin-rbac-groups-members-create-e748e0f1db.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fmembers%2Fcreate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
List RBAC Group Members
Add RBAC Group Member
Remove RBAC Group Member
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
5. [Members](/docs/en/api/http/beta/organization/rbac_groups/members)
# Add RBAC Group Member
POST/v1/organizations/rbac_groups/{group_id}/members
Add a User to an RBAC Group. Membership of groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
##### Body
user_id: string
ID of the User.
##### Returns
BetaRBACGroupMember object{ type: "rbac_group_member", created_at, email, 2 more }
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
defaultrbac_group_member
created_at: string
RFC 3339 timestamp of when the User was added to the RBAC Group.
formatdate-time
email: string
Email of the User.
group_id: string
ID of the RBAC Group.
user_id: string
ID of the User.
Add RBAC Group Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
}'
```
Response 200
```python
{
"created_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
}
```
##### Returns Examples
Response 200
```python
{
"created_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
---
## Admin/api-admin-rbac-groups-members-delete-5eb91f3908.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fmembers%2Fdelete)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
List RBAC Group Members
Add RBAC Group Member
Remove RBAC Group Member
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
5. [Members](/docs/en/api/http/beta/organization/rbac_groups/members)
# Remove RBAC Group Member
DELETE/v1/organizations/rbac_groups/{group_id}/members/{user_id}
Remove a User from an RBAC Group. Membership of groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
user_id: string
ID of the User.
##### Returns
BetaRBACGroupMemberDeleted object{ type: "rbac_group_member_deleted", group_id, user_id }
type: "rbac_group_member_deleted"
Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`.
defaultrbac_group_member_deleted
group_id: string
ID of the RBAC Group.
user_id: string
ID of the User.
Remove RBAC Group Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member_deleted",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
}
```
##### Returns Examples
Response 200
```python
{
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member_deleted",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
---
## Admin/api-admin-rbac-groups-members-list-5863ba67ba.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fmembers%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
List RBAC Group Members
Add RBAC Group Member
Remove RBAC Group Member
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
5. [Members](/docs/en/api/http/beta/organization/rbac_groups/members)
# List RBAC Group Members
GET/v1/organizations/rbac_groups/{group_id}/members
List members of an RBAC Group.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
##### Query parameters
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
page: optional string
Optionally set to the `next_page` token from the previous response.
##### Returns
data: array of [BetaRBACGroupMember](/docs/en/api/http/beta/organization/rbac_groups/members#beta_rbac_group_member) { type: "rbac_group_member", created_at, email, 2 more }
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
defaultrbac_group_member
created_at: string
RFC 3339 timestamp of when the User was added to the RBAC Group.
formatdate-time
email: string
Email of the User.
group_id: string
ID of the RBAC Group.
user_id: string
ID of the User.
has_more: boolean
Indicates if there are more results in the requested page direction.
next_page: string or null
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
List RBAC Group Members
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"created_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
}
],
"has_more": false,
"next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"created_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"type": "rbac_group_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
}
],
"has_more": false,
"next_page": "eyJjdXJzb3IiOiAicmJhY19ncm91cF8wMSJ9"
---
## Admin/api-admin-rbac-groups-retrieve-b1d2e8a041.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
# Get RBAC Group
GET/v1/organizations/rbac_groups/{group_id}
Retrieve an RBAC Group by ID.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
##### Returns
BetaRBACGroup object{ type: "rbac_group", id, created_at, 4 more }
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
defaultrbac_group
id: string
ID of the RBAC Group.
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
formatdate-time
name: string
Name of the RBAC Group. Not uniqueness-enforced.
roles: array of string or null
RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list.
source_type: "direct" or "scim"
How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider.
One of the following:
"direct"
"scim"
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
formatdate-time
Get RBAC Group
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-rbac-groups-update-dfda34d490.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_groups%2Fupdate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
List RBAC Groups
Get RBAC Group
Create RBAC Group
Update RBAC Group
Delete RBAC Group
Members
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Groups](/docs/en/api/http/beta/organization/rbac_groups)
# Update RBAC Group
POST/v1/organizations/rbac_groups/{group_id}
Update an RBAC Group's name. Groups provisioned by an identity provider (source type `"scim"`) cannot be modified via the API while an organization in the tenant uses SCIM provisioning.
The RBAC Groups API is available to Claude Enterprise organizations only.
##### Path parameters
group_id: string
ID of the RBAC Group.
##### Body
name: optional string or null
Name of the RBAC Group. Not uniqueness-enforced.
maxLength255
minLength1
##### Returns
BetaRBACGroup object{ type: "rbac_group", id, created_at, 4 more }
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
defaultrbac_group
id: string
ID of the RBAC Group.
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
formatdate-time
name: string
Name of the RBAC Group. Not uniqueness-enforced.
roles: array of string or null
RBAC Role IDs attached to this RBAC Group. Role attachment is managed in the admin settings and is read-only on this API. `null` means role data was temporarily unavailable — retry to distinguish from an empty list.
source_type: "direct" or "scim"
How the RBAC Group was created: `"direct"` for groups created directly (for example, in the organization's admin settings), `"scim"` for groups provisioned by the identity provider.
One of the following:
"direct"
"scim"
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
formatdate-time
Update RBAC Group
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-d '{
"name": "Engineering"
}'
```
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Engineering",
"roles": [
"rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s"
],
"source_type": "direct",
"type": "rbac_group",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-rbac-roles-fc6b4779e9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frbac_roles)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
List RBAC Roles
Get RBAC Role
Permissions
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# RBAC Roles
##### [List RBAC Roles](/docs/en/api/http/admin/rbac_roles/list)
GET/v1/organizations/rbac_roles
##### [Get RBAC Role](/docs/en/api/http/admin/rbac_roles/retrieve)
GET/v1/organizations/rbac_roles/{role_id}
##### Models
RbacRole object{ id, created_at, name, 2 more }
id: string
ID of the RBAC Role.
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
formatdate-time
name: string
Name of the RBAC Role.
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
defaultrbac_role
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
formatdate-time
#### RBAC Roles[Permissions](/docs/en/api/http/admin/rbac_roles/permissions)
##### [List RBAC Role Permissions](/docs/en/api/http/admin/rbac_roles/permissions/list)
GET/v1/organizations/rbac_roles/{role_id}/permissions
---
## Admin/api-admin-rbac-roles-list-51ed0cec46.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_roles%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
List RBAC Roles
Get RBAC Role
Permissions
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Roles](/docs/en/api/http/beta/organization/rbac_roles)
# List RBAC Roles
GET/v1/organizations/rbac_roles
List RBAC Roles in the organization.
The RBAC Roles API is available to Claude Enterprise organizations only.
##### Query parameters
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
page: optional string
Optionally set to the `next_page` token from the previous response.
##### Returns
data: array of [BetaRBACRole](/docs/en/api/http/beta/organization/rbac_roles#beta_rbac_role) { type: "rbac_role", id, created_at, 2 more }
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
defaultrbac_role
id: string
ID of the RBAC Role.
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
formatdate-time
name: string
Name of the RBAC Role.
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
formatdate-time
has_more: boolean
Indicates whether there are more results beyond this page.
next_page: string or null
Opaque cursor for the next page. Pass as the `page` parameter on the next request.
List RBAC Roles
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Project Editor",
"type": "rbac_role",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
],
"has_more": true,
"next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Project Editor",
"type": "rbac_role",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
],
"has_more": true,
"next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0"
---
## Admin/api-admin-rbac-roles-permissions-cfe1ce1dee.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Frbac_roles%2Fpermissions)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
List RBAC Roles
Get RBAC Role
Permissions
List RBAC Role Permissions
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [RBAC Roles](/docs/en/api/http/admin/rbac_roles)
# Permissions
##### [List RBAC Role Permissions](/docs/en/api/http/admin/rbac_roles/permissions/list)
GET/v1/organizations/rbac_roles/{role_id}/permissions
##### Models
RbacRolePermission object{ action, resource, type }
---
## Admin/api-admin-rbac-roles-permissions-list-380c9bac50.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_roles%2Fpermissions%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
List RBAC Roles
Get RBAC Role
Permissions
List RBAC Role Permissions
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Roles](/docs/en/api/http/beta/organization/rbac_roles)
5. [Permissions](/docs/en/api/http/beta/organization/rbac_roles/permissions)
# List RBAC Role Permissions
GET/v1/organizations/rbac_roles/{role_id}/permissions
List the permissions an RBAC Role grants.
The RBAC Roles API is available to Claude Enterprise organizations only.
##### Path parameters
role_id: string
ID of the RBAC Role.
##### Query parameters
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
page: optional string
Optionally set to the `next_page` token from the previous response.
##### Returns
data: array of [BetaRBACRolePermission](/docs/en/api/http/beta/organization/rbac_roles/permissions#beta_rbac_role_permission) { type: "rbac_role_permission", action, resource }
type: "rbac_role_permission"
Object type.
For RBAC Role Permissions, this is always `"rbac_role_permission"`.
defaultrbac_role_permission
action: string
Action the permission grants on the resource.
The vocabulary follows the resource: an `organization` grant carries a product-feature entitlement (for example `chat`), an admin-panel permission entitlement (`permission_*`), or a blanket capability-access mode — `capability_access_all` grants every product-feature entitlement, and `capability_access_all_ga` grants the generally-available subset as it stands at permission-check time; neither mode grants model-access entitlements. A consumer enumerating a role's per-feature grants should treat a blanket row as granting every product-feature entitlement it covers, or it will under-report the role's effective access. A `connector_tool` grant carries a tool-access action (`use` or `always_allow`); a `connector_scope` grant carries the scope action `grant` (the role may receive the named OAuth scope when tokens are minted for the connector); `connector` and `all_connectors` grants carry a tool-access action, the scope action, or an authentication-method action (`interactive` or `managed`).
resource: Organization or ConnectorTool or ConnectorScope or 2 more
What the permission applies to.
A tagged union: `type` names the kind of resource and determines which identifier fields are present.
One of the following:
Organization object{ type: "organization", organization_id }
type: "organization"
Kind of resource the permission applies to.
defaultorganization
organization_id: string
UUID of the organization the permission applies to.
ConnectorTool object{ type: "connector_tool", connector_id, tool_name }
type: "connector_tool"
Kind of resource the permission applies to.
defaultconnector_tool
connector_id: string
ID of the connector the permission applies to.
tool_name: string
Published name of the connector tool the permission applies to.
When the published name contains characters outside `[a-zA-Z0-9_-]` (or collides with a reserved form), it is server-encoded into a stable `{prefix}_{32-hex}` form — a shortened readable prefix of the name plus a hash — from which the published name is not recoverable.
ConnectorScope object{ type: "connector_scope", connector_id, scope }
type: "connector_scope"
Kind of resource the permission applies to.
defaultconnector_scope
connector_id: string
ID of the connector the permission applies to.
scope: string
OAuth scope the permission names — the role may receive this scope when tokens are minted for the connector.
Subject to the same encoding rule as `tool_name`: a scope containing characters outside `[a-zA-Z0-9_-]` (or colliding with a reserved form) appears server-encoded in a stable `{prefix}_{32-hex}` form. OAuth scopes routinely contain `:` and `/`, so most appear encoded.
Connector object{ type: "connector", connector_id }
type: "connector"
Kind of resource the permission applies to.
defaultconnector
connector_id: string
ID of the connector the permission applies to.
AllConnectors object{ type: "all_connectors" }
type: "all_connectors"
Kind of resource the permission applies to.
defaultall_connectors
has_more: boolean
Indicates whether there are more results beyond this page.
next_page: string or null
Opaque cursor for the next page. Pass as the `page` parameter on the next request.
List RBAC Role Permissions
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles/$ROLE_ID/permissions \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"action": "use",
"resource": {
"organization_id": "3c4f5e6d-7a8b-49c0-9d1e-2f3a4b5c6d7e",
"type": "organization"
},
"type": "rbac_role_permission"
}
],
"has_more": true,
"next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"action": "use",
"resource": {
"organization_id": "3c4f5e6d-7a8b-49c0-9d1e-2f3a4b5c6d7e",
"type": "organization"
},
"type": "rbac_role_permission"
}
],
"has_more": true,
"next_page": "eyJjdXJzb3IiOiAicmJhY19yb2xlXzAxIn0"
---
## Admin/api-admin-rbac-roles-retrieve-4fc2094763.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Frbac_roles%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
List RBAC Roles
Get RBAC Role
Permissions
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [RBAC Roles](/docs/en/api/http/beta/organization/rbac_roles)
# Get RBAC Role
GET/v1/organizations/rbac_roles/{role_id}
Retrieve an RBAC Role by ID.
The RBAC Roles API is available to Claude Enterprise organizations only.
##### Path parameters
role_id: string
ID of the RBAC Role.
##### Returns
BetaRBACRole object{ type: "rbac_role", id, created_at, 2 more }
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
defaultrbac_role
id: string
ID of the RBAC Role.
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
formatdate-time
name: string
Name of the RBAC Role.
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
formatdate-time
Get RBAC Role
cURL
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles/$ROLE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Project Editor",
"type": "rbac_role",
"updated_at": "2024-10-30T23:58:27.427722Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "rbac_role_016J8xVtKpDq3Wy9ZmN2hR4s",
"created_at": "2024-10-30T23:58:27.427722Z",
"name": "Project Editor",
"type": "rbac_role",
"updated_at": "2024-10-30T23:58:27.427722Z"
---
## Admin/api-admin-service-accounts-a7221288ed.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Service Accounts
##### [Create Service Account](/docs/en/api/http/admin/service_accounts/create)
POST/v1/organizations/service_accounts
##### [Get Service Account](/docs/en/api/http/admin/service_accounts/retrieve)
GET/v1/organizations/service_accounts/{service_account_id}
##### [List Service Accounts](/docs/en/api/http/admin/service_accounts/list)
GET/v1/organizations/service_accounts
##### [Update Service Account](/docs/en/api/http/admin/service_accounts/update)
POST/v1/organizations/service_accounts/{service_account_id}
##### [Archive Service Account](/docs/en/api/http/admin/service_accounts/archive)
POST/v1/organizations/service_accounts/{service_account_id}/archive
##### Models
ServiceAccount object{ id, archived_at, archived_by_actor_id, 8 more }
Named non-human identity within the caller's organization.
A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).
#### Service Accounts[Workspaces](/docs/en/api/http/admin/service_accounts/workspaces)
##### [Add Workspace To Service Account](/docs/en/api/http/admin/service_accounts/workspaces/create)
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [List Workspaces For Service Account](/docs/en/api/http/admin/service_accounts/workspaces/list)
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [Remove Workspace From Service Account](/docs/en/api/http/admin/service_accounts/workspaces/delete)
DELETE/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}
---
## Admin/api-admin-service-accounts-archive-9e6baf58e9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Farchive)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# Archive Service Account
POST/v1/organizations/service_accounts/{service_account_id}/archive
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Archive a service account.
Idempotent; re-archiving returns the service account with its original `archived_at`. Rejected with 400 if any live (non-archived) federation rule still targets this service account, same as issuer archival; archive those rules first or change their target to another service account.
##### Path parameters
service_account_id: string
ID of the service account to archive.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
ServiceAccount object{ id, archived_at, archived_by_actor_id, 8 more }
Named non-human identity within the caller's organization.
A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).
Archive Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-service-accounts-create-3048bc47a1.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# Create Service Account
POST/v1/organizations/service_accounts
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Create a service account.
A service account is a named workload identity that federation rules target. `organization_role` is `developer` (default) or `admin`; a rule may only be created or retargeted to grant `org:admin` scope when the target's `organization_role` is `admin`. Creating an `admin`-role service account requires an interactive credential (a user OAuth token or a Console session) — a workload may only create `developer`-role service accounts.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
maxLength255
minLength1
description: optional string or null
Optional free-text description.
maxLength2000
organization_role: optional "admin" or "developer"
Org-level role. Defaults to `developer`.
One of the following:
"admin"
"developer"
##### Returns
ServiceAccount object{ id, archived_at, archived_by_actor_id, 8 more }
Named non-human identity within the caller's organization.
A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).
Create Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"name": "ci-deploy-bot"
}'
```
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-service-accounts-list-75718033c1.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# List Service Accounts
GET/v1/organizations/service_accounts
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List service accounts in the caller's organization.
Results are ordered by creation time, newest first. Use `limit` and the `next_page` cursor to paginate; set `include_archived=true` to include archived service accounts.
##### Query parameters
include_archived: optional boolean
Include archived resources. Defaults to false.
defaultfalse
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of [ServiceAccount](/docs/en/api/http/admin/service_accounts#service_account) { id, archived_at, archived_by_actor_id, 8 more }
id: string
Tagged ID of the service account.
archived_at: string or null
If set, this service account is archived.
formatdate-time
archived_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
created_at: string
When this service account was created.
formatdate-time
created_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
description: string or null
Optional free-text description.
name: string
Admin-chosen slug identifier.
organization_role: "admin" or "developer"
Org-level role. A federation rule may only be created or retargeted to grant `org:admin` scope when this is `admin`. A rule granting `org:admin` whose target is later demoted to `developer` is rejected at token exchange. Rules granting `org:admin` are managed in the Console.
One of the following:
"admin"
"developer"
type: "service_account"
defaultservice_account
updated_at: string
When this service account was last updated.
formatdate-time
updated_by_actor_id: string or null
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
next_page: string or null
Opaque cursor for the next page, or null if no more results.
List Service Accounts
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-service-accounts-retrieve-6eaade2a66.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# Get Service Account
GET/v1/organizations/service_accounts/{service_account_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Retrieve a service account by its ID (`svac_...`).
##### Path parameters
service_account_id: string
ID of the service account.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
ServiceAccount object{ id, archived_at, archived_by_actor_id, 8 more }
Named non-human identity within the caller's organization.
A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).
Get Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-service-accounts-update-eea73dae86.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# Update Service Account
POST/v1/organizations/service_accounts/{service_account_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Update a service account.
Only `description` and `organization_role` are mutable; `name` cannot be changed. Archived service accounts cannot be updated; this returns 400. Setting `organization_role` to `admin` (even when unchanged) requires an interactive credential (a user OAuth token or a Console session).
##### Path parameters
service_account_id: string
ID of the service account to update.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
description: optional string or null
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string).
maxLength2000
organization_role: optional "admin" or "developer" or null
Replaces the org-level role. Omit or send `null` to leave unchanged.
One of the following:
"admin"
"developer"
##### Returns
ServiceAccount object{ id, archived_at, archived_by_actor_id, 8 more }
Named non-human identity within the caller's organization.
A service account is a pure identity: name + org. Authorization lives on whatever references it (federation rules).
Update Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
}
```
##### Returns Examples
Response 200
```python
{
"id": "svac_01SDCCSbTxrXDpWc1phhtcfK",
"archived_at": "2019-12-27T18:11:19.117Z",
"archived_by_actor_id": "archived_by_actor_id",
"created_at": "2024-10-30T23:58:27.427722Z",
"created_by_actor_id": "created_by_actor_id",
"description": "description",
"name": "ci-deploy-bot",
"organization_role": "admin",
"type": "service_account",
"updated_at": "2024-10-30T23:58:27.427722Z",
"updated_by_actor_id": "updated_by_actor_id"
---
## Admin/api-admin-service-accounts-workspaces-create-44d1cc3747.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fworkspaces%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Add Workspace To Service Account
List Workspaces For Service Account
Remove Workspace From Service Account
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
4. [Workspaces](/docs/en/api/http/admin/service_accounts/workspaces)
# Add Workspace To Service Account
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Add a service account to a workspace with the given `workspace_role`.
Mirror of `POST /workspaces/{workspace_id}/service_accounts`, addressed from the service-account side; both create the same membership. If the service account is already an explicit member of the workspace, its `workspace_role` is replaced with the value supplied here. Archived workspaces return 400. Archived service accounts cannot be added and are rejected.
##### Path parameters
service_account_id: string
ID of the service account.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
workspace_id: string
Tagged workspace ID to add the service account to.
workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"
Role to assign to the service account in this workspace.
One of the following:
"workspace_admin"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
##### Returns
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Add Workspace To Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}'
```
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
```
##### Returns Examples
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-service-accounts-workspaces-delete-7f7758bd00.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fworkspaces%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Add Workspace To Service Account
List Workspaces For Service Account
Remove Workspace From Service Account
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
4. [Workspaces](/docs/en/api/http/admin/service_accounts/workspaces)
# Remove Workspace From Service Account
DELETE/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Remove a service account from a workspace.
Mirror of `DELETE /workspaces/{workspace_id}/service_accounts/{service_account_id}`, addressed from the service-account side. Removal is idempotent (returns 200 even if the membership was already removed). A DELETE against the implicit default-workspace membership returns 200 but is a no-op and the membership persists; deleting an explicit default-workspace row reverts to the implicit `workspace_user` membership. Archived workspaces return 400.
##### Path parameters
service_account_id: string
ID of the service account.
workspace_id: string
ID of the workspace.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
service_account_id: string
Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op.
type: "service_account_workspace_member_deleted"
defaultservice_account_workspace_member_deleted
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
Remove Workspace From Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces/$WORKSPACE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"service_account_id": "service_account_id",
"type": "service_account_workspace_member_deleted",
"workspace_id": "workspace_id"
}
```
##### Returns Examples
Response 200
```python
{
"service_account_id": "service_account_id",
"type": "service_account_workspace_member_deleted",
"workspace_id": "workspace_id"
---
## Admin/api-admin-service-accounts-workspaces-e62871b9be.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fworkspaces)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Add Workspace To Service Account
List Workspaces For Service Account
Remove Workspace From Service Account
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
# Workspaces
##### [Add Workspace To Service Account](/docs/en/api/http/admin/service_accounts/workspaces/create)
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [List Workspaces For Service Account](/docs/en/api/http/admin/service_accounts/workspaces/list)
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [Remove Workspace From Service Account](/docs/en/api/http/admin/service_accounts/workspaces/delete)
DELETE/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}
##### Models
WorkspaceCreateResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
WorkspaceListResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
WorkspaceDeleteResponse object{ service_account_id, type, workspace_id }
service_account_id: string
Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op.
type: "service_account_workspace_member_deleted"
defaultservice_account_workspace_member_deleted
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
---
## Admin/api-admin-service-accounts-workspaces-list-80f1df435c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fservice_accounts%2Fworkspaces%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Create Service Account
Get Service Account
List Service Accounts
Update Service Account
Archive Service Account
Workspaces
Add Workspace To Service Account
List Workspaces For Service Account
Remove Workspace From Service Account
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Service Accounts](/docs/en/api/http/admin/service_accounts)
4. [Workspaces](/docs/en/api/http/admin/service_accounts/workspaces)
# List Workspaces For Service Account
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List the workspaces a service account is a member of.
Each entry includes the service account's `workspace_role` in that workspace. Use `limit` and the `next_page` cursor to paginate. When the service account has no explicit default-workspace membership, the implicit (`implicit: true`) membership is returned as the first entry on the first page; with `limit=1` the first page may return up to 2 entries (the implicit entry plus one explicit membership) so a pagination cursor can be derived. Memberships are returned only while the service account is active. Without a `page` cursor, an archived service account returns an empty list. A `page` cursor that does not match an active membership returns a 400 invalid-request error. A cursor stops matching when the membership is removed, the workspace is deleted, or the service account is archived. Restart pagination from the first page to recover.
##### Path parameters
service_account_id: string
ID of the service account.
##### Query parameters
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
next_page: string or null
Opaque cursor for the next page, or null if no more results.
List Workspaces For Service Account
cURL
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-spend-limits-95db77e800.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Spend Limits
##### [Set Spend Limit](/docs/en/api/http/admin/spend_limits/create)
POST/v1/organizations/spend_limits
##### [Get Spend Limit](/docs/en/api/http/admin/spend_limits/retrieve)
GET/v1/organizations/spend_limits/{spend_limit_id}
##### [Delete Spend Limit](/docs/en/api/http/admin/spend_limits/delete)
DELETE/v1/organizations/spend_limits/{spend_limit_id}
##### [List Effective Spend Limits](/docs/en/api/http/admin/spend_limits/list_effective)
GET/v1/organizations/spend_limits/effective
##### Models
SpendLimit object{ id, amount, created_at, 5 more }
A configured spend limit: a cap on metered spend for one scope and period.
SpendSummary object{ actor, amount, currency, 5 more }
Per-member effective-limit report row (`GET /spend_limits/effective`).
SpendLimitDeleteResponse object{ id, type }
id: string
type: "spend_limit_deleted"
defaultspend_limit_deleted
#### Spend Limits[Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests)
##### [List Spend Limit Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests/list)
GET/v1/organizations/spend_limit_increase_requests
##### [Get Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/retrieve)
GET/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}
##### [Approve Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/approve)
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/approve
##### [Deny Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/deny)
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/deny
---
## Admin/api-admin-spend-limits-create-abf50c58a6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
# Set Spend Limit
POST/v1/organizations/spend_limits
Set a per-user spend limit override.
Upsert keyed on (scope, period): setting a limit that already exists overwrites it in place. Only `scope.type: "user"` is accepted; seat-tier, group, and organization-level defaults are configured in claude.ai.
##### Body
amount: string or null
Limit amount as a non-negative integer decimal string in the minor unit of the organization's billing currency (cents for USD): "50000" is \$500.00. `null` sets an explicit no-limit override for this scope and `period` only — each period resolves independently, so caps for other periods still apply.
scope: object{ type, user_id }
Scope selecting a single member of the organization.
type: "user"
Scope type. Always `user` for this scope.
defaultuser
user_id: string
Tagged ID of the member the spend limit applies to.
period: optional "daily" or "monthly" or "weekly"
One of the following:
"daily"
"monthly"
"weekly"
##### Returns
SpendLimit object{ id, amount, created_at, 5 more }
A configured spend limit: a cap on metered spend for one scope and period.
Set Spend Limit
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limits \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"amount": "50000",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"period": "monthly"
}'
```
Response 200
```python
{
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
---
## Admin/api-admin-spend-limits-delete-427c3b0186.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
# Delete Spend Limit
DELETE/v1/organizations/spend_limits/{spend_limit_id}
Delete a per-user spend limit override.
The member falls back to any inherited spend limit at that period. Seat-tier, group, and organization-level rows cannot be deleted via this endpoint.
##### Path parameters
spend_limit_id: string
ID of the Spend Limit.
##### Returns
id: string
type: "spend_limit_deleted"
defaultspend_limit_deleted
Delete Spend Limit
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limits/$SPEND_LIMIT_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
---
## Admin/api-admin-spend-limits-increase-requests-3a1990d08a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fincrease_requests)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
List Spend Limit Increase Requests
Get Spend Limit Increase Request
Approve Spend Limit Increase Request
Deny Spend Limit Increase Request
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
# Increase Requests
##### [List Spend Limit Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests/list)
GET/v1/organizations/spend_limit_increase_requests
##### [Get Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/retrieve)
GET/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}
##### [Approve Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/approve)
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/approve
##### [Deny Spend Limit Increase Request](/docs/en/api/http/admin/spend_limits/increase_requests/deny)
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/deny
##### Models
SpendLimitIncreaseRequest object{ id, actor, created_at, 6 more }
IncreaseRequestApproveResponse object{ id, actor, created_at, 7 more }
---
## Admin/api-admin-spend-limits-increase-requests-approve-0bf6343e8d.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fincrease_requests%2Fapprove)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
List Spend Limit Increase Requests
Get Spend Limit Increase Request
Approve Spend Limit Increase Request
Deny Spend Limit Increase Request
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
4. [Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests)
# Approve Spend Limit Increase Request
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/approve
Approve a pending spend limit increase request.
Writes a per-user spend limit at `amount` for the requester and transitions the request to `approved`. `period` defaults to the period the member was blocked on. Anthropic emails the requester unless `suppress_notification` is set.
##### Path parameters
spend_limit_increase_request_id: string
ID of the spend limit increase request.
##### Body
amount: string
New per-user spend limit as a non-negative integer decimal string (minor units).
period: optional "daily" or "monthly" or "weekly" or null
One of the following:
"daily"
"monthly"
"weekly"
suppress_notification: optional boolean
##### Returns
id: string
actor: object{ deleted, email_address, name, 2 more }
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
deleted: boolean
True only when the underlying account has been deleted.
defaultfalse
email_address: string or null
The user's email address. Null when the account is unavailable or has been deleted.
name: string or null
The user's current display name. Null when the account is unavailable, has been deleted, or has no name set.
type: "user_actor"
Actor type. Always `user_actor`.
defaultuser_actor
user_id: string
Tagged ID of the user.
created_at: string
formatdate-time
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
"monthly"
"weekly"
resolved_at: string or null
formatdate-time
resolved_by: object{ deleted, email_address, name, 2 more } or object{ scoped_api_key_id, type } or null
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
One of the following:
UserActor object{ deleted, email_address, name, 2 more }
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
deleted: boolean
True only when the underlying account has been deleted.
defaultfalse
email_address: string or null
The user's email address. Null when the account is unavailable or has been deleted.
name: string or null
The user's current display name. Null when the account is unavailable, has been deleted, or has no name set.
type: "user_actor"
Actor type. Always `user_actor`.
defaultuser_actor
user_id: string
Tagged ID of the user.
ScopedAPIKeyActor object{ scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
type: "scoped_api_key_actor"
defaultscoped_api_key_actor
spend_limit: [SpendLimit](/docs/en/api/http/admin/spend_limits#spend_limit) { id, amount, created_at, 5 more }
A configured spend limit: a cap on metered spend for one scope and period.
spend_summary: [SpendSummary](/docs/en/api/http/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more } or null
Per-member effective-limit report row (`GET /spend_limits/effective`).
status: "approved" or "denied" or "pending"
One of the following:
"approved"
"denied"
"pending"
type: "spend_limit_increase_request"
defaultspend_limit_increase_request
Approve Spend Limit Increase Request
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/$SPEND_LIMIT_INCREASE_REQUEST_ID/approve \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"amount": "50000",
"period": "monthly"
}'
```
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit": {
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
}
```
##### Returns Examples
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit": {
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
---
## Admin/api-admin-spend-limits-increase-requests-deny-176d56e0d9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fincrease_requests%2Fdeny)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
List Spend Limit Increase Requests
Get Spend Limit Increase Request
Approve Spend Limit Increase Request
Deny Spend Limit Increase Request
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
4. [Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests)
# Deny Spend Limit Increase Request
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/deny
Deny a pending spend limit increase request.
Idempotent on `denied`; denying an already-`approved` request returns 400. Anthropic emails the requester unless `suppress_notification` is set.
##### Path parameters
spend_limit_increase_request_id: string
ID of the spend limit increase request.
##### Body
suppress_notification: optional boolean
##### Returns
SpendLimitIncreaseRequest object{ id, actor, created_at, 6 more }
Deny Spend Limit Increase Request
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/$SPEND_LIMIT_INCREASE_REQUEST_ID/deny \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
}
```
##### Returns Examples
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
---
## Admin/api-admin-spend-limits-increase-requests-list-0415944636.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fincrease_requests%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
List Spend Limit Increase Requests
Get Spend Limit Increase Request
Approve Spend Limit Increase Request
Deny Spend Limit Increase Request
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
4. [Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests)
# List Spend Limit Increase Requests
GET/v1/organizations/spend_limit_increase_requests
List spend limit increase requests, most recent first.
Pending requests include a live `spend_summary` for the requester. Requests whose requester is no longer a member are excluded.
##### Query parameters
actor_ids: optional array of string
Filter by requester, as `user_...` tagged IDs.
limit: optional number
default20
maximum1000
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
status: optional array of "approved" or "denied" or "pending"
Filter by status. Omit to return all.
One of the following:
"approved"
"denied"
"pending"
##### Returns
data: array of [SpendLimitIncreaseRequest](/docs/en/api/http/admin/spend_limits/increase_requests#spend_limit_increase_request) { id, actor, created_at, 6 more }
id: string
actor: object{ deleted, email_address, name, 2 more }
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
deleted: boolean
True only when the underlying account has been deleted.
defaultfalse
email_address: string or null
The user's email address. Null when the account is unavailable or has been deleted.
name: string or null
The user's current display name. Null when the account is unavailable, has been deleted, or has no name set.
type: "user_actor"
Actor type. Always `user_actor`.
defaultuser_actor
user_id: string
Tagged ID of the user.
created_at: string
formatdate-time
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
"monthly"
"weekly"
resolved_at: string or null
formatdate-time
resolved_by: object{ deleted, email_address, name, 2 more } or object{ scoped_api_key_id, type } or null
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
One of the following:
UserActor object{ deleted, email_address, name, 2 more }
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
deleted: boolean
True only when the underlying account has been deleted.
defaultfalse
email_address: string or null
The user's email address. Null when the account is unavailable or has been deleted.
name: string or null
The user's current display name. Null when the account is unavailable, has been deleted, or has no name set.
type: "user_actor"
Actor type. Always `user_actor`.
defaultuser_actor
user_id: string
Tagged ID of the user.
ScopedAPIKeyActor object{ scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
type: "scoped_api_key_actor"
defaultscoped_api_key_actor
spend_summary: [SpendSummary](/docs/en/api/http/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more } or null
Per-member effective-limit report row (`GET /spend_limits/effective`).
status: "approved" or "denied" or "pending"
One of the following:
"approved"
"denied"
"pending"
type: "spend_limit_increase_request"
defaultspend_limit_increase_request
next_page: string or null
List Spend Limit Increase Requests
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limit_increase_requests \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
---
## Admin/api-admin-spend-limits-increase-requests-retrieve-597b0bf669.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fincrease_requests%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
List Spend Limit Increase Requests
Get Spend Limit Increase Request
Approve Spend Limit Increase Request
Deny Spend Limit Increase Request
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
4. [Increase Requests](/docs/en/api/http/admin/spend_limits/increase_requests)
# Get Spend Limit Increase Request
GET/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}
Retrieve a spend limit increase request.
While `pending`, the response includes a live `spend_summary` for the requester at the request's period.
##### Path parameters
spend_limit_increase_request_id: string
ID of the spend limit increase request.
##### Returns
SpendLimitIncreaseRequest object{ id, actor, created_at, 6 more }
Get Spend Limit Increase Request
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/$SPEND_LIMIT_INCREASE_REQUEST_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
}
```
##### Returns Examples
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"created_at": "2019-12-27T18:11:19.117Z",
"period": "monthly",
"resolved_at": "2019-12-27T18:11:19.117Z",
"resolved_by": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
},
"status": "approved",
"type": "spend_limit_increase_request"
---
## Admin/api-admin-spend-limits-list-effective-22e3bdbcfd.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Flist_effective)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
# List Effective Spend Limits
GET/v1/organizations/spend_limits/effective
List each member's effective spend limit and period-to-date spend.
Returns one row per (member, period) the member resolves a spend limit for, with the `source` scope the spend limit was inherited from. Paginates by member, so a member's periods never split across pages.
##### Query parameters
limit: optional number
Maximum number of members per page. A member's period rows never split across pages, so a page may carry more rows than this. Defaults to `20`.
default20
maximum1000
minimum1
page: optional string
Opaque cursor from a previous response's `next_page` field.
period: optional array of "daily" or "monthly" or "weekly"
Restrict the report to these limit periods. Omit to return one row per period each member resolves a spend limit for.
maxItems3
One of the following:
"daily"
"monthly"
"weekly"
user_ids: optional array of string
Restrict the report to these members, by tagged user ID (`user_...`). At most 100 entries.
maxItems100
##### Returns
data: array of [SpendSummary](/docs/en/api/http/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
actor: object{ deleted, email_address, name, 2 more }
A user within the organization. `name` and `email_address` are null when the underlying account is unavailable or has been deleted; `deleted` is true only for deleted accounts.
deleted: boolean
True only when the underlying account has been deleted.
defaultfalse
email_address: string or null
The user's email address. Null when the account is unavailable or has been deleted.
name: string or null
The user's current display name. Null when the account is unavailable, has been deleted, or has no name set.
type: "user_actor"
Actor type. Always `user_actor`.
defaultuser_actor
user_id: string
Tagged ID of the user.
amount: string or null
Effective limit amount as a non-negative integer decimal string in the minor unit of `currency` (cents for USD). `null` means no limit applies for this row's `period` — each period resolves independently, so another period may still cap this member.
currency: string
ISO 4217 code of the organization's billing currency; the unit for `amount` and `period_to_date_spend`.
period: "daily" or "monthly" or "weekly"
Period this row's effective limit and spend are reported for.
One of the following:
"daily"
"monthly"
"weekly"
period_to_date_spend: string
The member's spend so far in the current period, as a non-negative decimal string in the minor unit of `currency` (cents for USD). May carry fractional minor units up to three decimal places (e.g. `"12050.5"`) — metered usage is not rounded to whole cents. Reads as `"0"` when the spend reading is temporarily unavailable.
scope: object{ type, user_id }
Scope selecting a single member of the organization.
type: "user"
Scope type. Always `user` for this scope.
defaultuser
user_id: string
Tagged ID of the member the spend limit applies to.
source: object{ type, user_id } or object{ seat_tier, type } or object{ rbac_group_id, type } or 2 more
Scope selecting a single member of the organization.
One of the following:
User object{ type, user_id }
Scope selecting a single member of the organization.
type: "user"
Scope type. Always `user` for this scope.
defaultuser
user_id: string
Tagged ID of the member the spend limit applies to.
SeatTier object{ seat_tier, type }
seat_tier: string
type: "seat_tier"
defaultseat_tier
RbacGroup object{ rbac_group_id, type }
rbac_group_id: string
type: "rbac_group"
defaultrbac_group
OrganizationService object{ service, type }
service: string
type: "organization_service"
defaultorganization_service
Organization object{ type }
type: "organization"
defaultorganization
spend_limit_id: string
next_page: string or null
List Effective Spend Limits
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limits/effective \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "12050.5",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"source": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"spend_limit_id": "spend_limit_id"
---
## Admin/api-admin-spend-limits-retrieve-ff62e5b39b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fspend_limits%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Set Spend Limit
Get Spend Limit
Delete Spend Limit
List Effective Spend Limits
Increase Requests
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Spend Limits](/docs/en/api/http/admin/spend_limits)
# Get Spend Limit
GET/v1/organizations/spend_limits/{spend_limit_id}
Retrieve a spend limit by ID.
##### Path parameters
spend_limit_id: string
ID of the Spend Limit.
##### Returns
SpendLimit object{ id, amount, created_at, 5 more }
A configured spend limit: a cap on metered spend for one scope and period.
Get Spend Limit
cURL
```python
curl https://api.anthropic.com/v1/organizations/spend_limits/$SPEND_LIMIT_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
}
```
##### Returns Examples
Response 200
```python
{
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q"
},
"type": "spend_limit",
"updated_at": "2019-12-27T18:11:19.117Z"
---
## Admin/api-admin-usage-report-b05de342cf.md
# Usage Report
## Retrieve Messages
**get** `/v1/organizations/usage_report/messages`
Get Messages Usage Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `account_ids: optional array of string`
Restrict usage returned to the specified user account ID(s).
- `api_key_ids: optional array of string`
Restrict usage returned to the specified API key ID(s).
- `bucket_width: optional "1d" or "1m" or "1h"`
Time granularity of the response data.
- `"1d"`
- `"1m"`
- `"1h"`
- `context_window: optional array of "0-200k" or "200k-1M"`
Restrict usage returned to the specified context window(s).
- `"0-200k"`
- `"200k-1M"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more`
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
- `"api_key_id"`
- `"workspace_id"`
- `"model"`
- `"service_tier"`
- `"context_window"`
- `"inference_geo"`
- `"speed"`
- `"account_id"`
- `"service_account_id"`
- `inference_geos: optional array of "global" or "us" or "not_available"`
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
- `"global"`
- `"us"`
- `"not_available"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
The default and max limits depend on `bucket_width`:
• `"1d"`: Default of 7 days, maximum of 31 days
• `"1h"`: Default of 24 hours, maximum of 168 hours
• `"1m"`: Default of 60 minutes, maximum of 1440 minutes
- `models: optional array of string`
Restrict usage returned to the specified model(s).
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
- `service_account_ids: optional array of string`
Restrict usage returned to the specified service account ID(s).
- `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more`
Restrict usage returned to the specified service tier(s).
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `speeds: optional array of "standard" or "fast"`
Restrict usage returned to the specified speed(s) (Claude Code research preview).
Requires the `fast-mode-2026-02-01` beta header.
- `"standard"`
- `"fast"`
- `workspace_ids: optional array of string`
Restrict usage returned to the specified workspace ID(s).
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Retrieve Claude Code
**get** `/v1/organizations/usage_report/claude_code`
Retrieve daily aggregated usage metrics for Claude Code users.
Enables organizations to analyze developer productivity and build custom dashboards.
### Query Parameters
- `starting_at: string`
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
- `limit: optional number`
Number of records per page (default: 20, max: 1000).
- `page: optional string`
Opaque cursor token from previous response's `next_page` field.
### Returns
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Claude Code Usage Report
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Messages Usage Report
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-usage-report-f1f271ff94.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fusage_report)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Get Messages Usage Report
Get Claude Code Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Usage Report
##### [Get Messages Usage Report](/docs/en/api/http/admin/usage_report/retrieve_messages)
GET/v1/organizations/usage_report/messages
##### [Get Claude Code Usage Report](/docs/en/api/http/admin/usage_report/retrieve_claude_code)
GET/v1/organizations/usage_report/claude_code
##### Models
ClaudeCodeUsageReport object{ data, has_more, next_page }
MessagesUsageReport object{ data, has_more, next_page }
---
## Admin/api-admin-usage-report-retrieve-claude-code-610a5cf4a0.md
## Retrieve Claude Code
**get** `/v1/organizations/usage_report/claude_code`
Retrieve daily aggregated usage metrics for Claude Code users.
Enables organizations to analyze developer productivity and build custom dashboards.
### Query Parameters
- `starting_at: string`
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
- `limit: optional number`
Number of records per page (default: 20, max: 1000).
- `page: optional string`
Opaque cursor token from previous response's `next_page` field.
### Returns
- `ClaudeCodeUsageReport = object { data, has_more, next_page }`
- `data: array of object { actor, core_metrics, customer_type, 6 more }`
List of Claude Code usage records for the requested date.
- `actor: object { email_address, type } or object { api_key_name, type }`
The user or API key that performed the Claude Code actions.
- `UserActor = object { email_address, type }`
- `email_address: string`
Email address of the user who performed Claude Code actions.
- `type: "user_actor"`
- `"user_actor"`
- `APIActor = object { api_key_name, type }`
- `api_key_name: string`
Name of the API key used to perform Claude Code actions.
- `type: "api_actor"`
- `"api_actor"`
- `core_metrics: object { commits_by_claude_code, lines_of_code, num_sessions, pull_requests_by_claude_code }`
Core productivity metrics measuring Claude Code usage and impact.
- `commits_by_claude_code: number`
Number of git commits created through Claude Code's commit functionality.
- `lines_of_code: object { added, removed }`
Statistics on code changes made through Claude Code.
- `added: number`
Total number of lines of code added across all files by Claude Code.
- `removed: number`
Total number of lines of code removed across all files by Claude Code.
- `num_sessions: number`
Number of distinct Claude Code sessions initiated by this actor.
- `pull_requests_by_claude_code: number`
Number of pull requests created through Claude Code's PR functionality.
- `customer_type: "api" or "subscription"`
Type of customer account (api for API customers, subscription for Pro/Team customers).
- `"api"`
- `"subscription"`
- `date: string`
UTC date for the usage metrics in YYYY-MM-DD format.
- `model_breakdown: array of object { estimated_cost, model, tokens }`
Token usage and cost breakdown by AI model used.
- `estimated_cost: object { amount, currency }`
Estimated cost for using this model
- `amount: number`
Estimated cost amount in minor currency units (e.g., cents for USD).
- `currency: string`
Currency code for the estimated cost (e.g., 'USD').
- `model: string`
Name of the AI model used for Claude Code interactions.
- `tokens: object { cache_creation, cache_read, input, output }`
Token usage breakdown for this model
- `cache_creation: number`
Number of cache creation tokens consumed by this model.
- `cache_read: number`
Number of cache read tokens consumed by this model.
- `input: number`
Number of input tokens consumed by this model.
- `output: number`
Number of output tokens generated by this model.
- `organization_id: string`
ID of the organization that owns the Claude Code usage.
- `terminal_type: string`
Type of terminal or environment where Claude Code was used.
- `tool_actions: map[object { accepted, rejected } ]`
Breakdown of tool action acceptance and rejection rates by tool type.
- `accepted: number`
Number of tool action proposals that the user accepted.
- `rejected: number`
Number of tool action proposals that the user rejected.
- `subscription_type: optional "enterprise" or "team"`
Subscription tier for subscription customers. `null` for API customers.
- `"enterprise"`
- `"team"`
- `has_more: boolean`
True if there are more records available beyond the current page.
- `next_page: string`
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-usage-report-retrieve-claude-code-fefdc219f3.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fusage_report%2Fretrieve_claude_code)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Usage Report
Get Messages Usage Report
Get Claude Code Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Usage Report](/docs/en/api/http/beta/organization/usage_report)
# Get Claude Code Usage Report
GET/v1/organizations/usage_report/claude_code
Retrieve daily aggregated usage metrics for Claude Code users. Enables organizations to analyze developer productivity and build custom dashboards.
##### Query parameters
starting_at: string
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
pattern^\d{4}-\d{2}-\d{2}\$
formatdate
limit: optional number
Number of records per page (default: 20, max: 1000).
default20
maximum1000
minimum1
page: optional string
Opaque cursor token from previous response's `next_page` field.
##### Returns
BetaClaudeCodeUsageReport object{ data, has_more, next_page }
Get Claude Code Usage Report
cURL
```python
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"actor": {
"email_address": "user@emaildomain.com",
"type": "user_actor"
},
"core_metrics": {
"commits_by_claude_code": 8,
"lines_of_code": {
"added": 342,
"removed": 128
},
"num_sessions": 15,
"pull_requests_by_claude_code": 2
},
"customer_type": "api",
"date": "2025-08-08T00:00:00Z",
"is_remote": false,
"model_breakdown": [
{
"estimated_cost": {
"amount": 186,
"currency": "USD"
},
"model": "claude-opus-5",
"tokens": {
"cache_creation": 2340,
"cache_read": 8790,
"input": 45230,
"output": 12450
}
},
{
"estimated_cost": {
"amount": 42,
"currency": "USD"
},
"model": "claude-sonnet-5",
"tokens": {
"cache_creation": 890,
"cache_read": 3420,
"input": 23100,
"output": 5680
}
}
],
"organization_id": "12345678-1234-5678-1234-567812345678",
"terminal_type": "iTerm.app",
"tool_actions": {
"edit_tool": {
"accepted": 25,
"rejected": 3
},
"multi_edit_tool": {
"accepted": 12,
"rejected": 1
},
"notebook_edit_tool": {
"accepted": 5,
"rejected": 2
},
"write_tool": {
"accepted": 8,
"rejected": 0
}
},
"subscription_type": "enterprise"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"email_address": "user@emaildomain.com",
"type": "user_actor"
},
"core_metrics": {
"commits_by_claude_code": 8,
"lines_of_code": {
"added": 342,
"removed": 128
},
"num_sessions": 15,
"pull_requests_by_claude_code": 2
},
"customer_type": "api",
"date": "2025-08-08T00:00:00Z",
"is_remote": false,
"model_breakdown": [
{
"estimated_cost": {
"amount": 186,
"currency": "USD"
},
"model": "claude-opus-5",
"tokens": {
"cache_creation": 2340,
"cache_read": 8790,
"input": 45230,
"output": 12450
}
},
{
"estimated_cost": {
"amount": 42,
"currency": "USD"
},
"model": "claude-sonnet-5",
"tokens": {
"cache_creation": 890,
"cache_read": 3420,
"input": 23100,
"output": 5680
}
}
],
"organization_id": "12345678-1234-5678-1234-567812345678",
"terminal_type": "iTerm.app",
"tool_actions": {
"edit_tool": {
"accepted": 25,
"rejected": 3
},
"multi_edit_tool": {
"accepted": 12,
"rejected": 1
},
"notebook_edit_tool": {
"accepted": 5,
"rejected": 2
},
"write_tool": {
"accepted": 8,
"rejected": 0
}
},
"subscription_type": "enterprise"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
---
## Admin/api-admin-usage-report-retrieve-messages-108f06193f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fusage_report%2Fretrieve_messages)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Get Messages Usage Report
Get Claude Code Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Usage Report](/docs/en/api/http/admin/usage_report)
# Get Messages Usage Report
GET/v1/organizations/usage_report/messages
Get Messages Usage Report
##### Query parameters
starting_at: string
Time buckets that start on or after this RFC 3339 timestamp will be returned. Each time bucket will be snapped to the start of the minute/hour/day in UTC.
formatdate-time
account_ids: optional array of string
Restrict usage returned to the specified user account ID(s).
api_key_ids: optional array of string
Restrict usage returned to the specified API key ID(s).
bucket_width: optional "1d" or "1h" or "1m"
Time granularity of the response data.
default1d
One of the following:
"1d"
"1h"
"1m"
context_window: optional array of "0-200k" or "200k-1M"
Restrict usage returned to the specified context window(s).
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
Time buckets that end before this RFC 3339 timestamp will be returned.
formatdate-time
group_by: optional array of "account_id" or "api_key_id" or "context_window" or 6 more
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
One of the following:
"account_id"
"api_key_id"
"context_window"
"inference_geo"
"model"
"service_account_id"
"service_tier"
"speed"
"workspace_id"
inference_geos: optional array of "global" or "not_available" or "us"
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
One of the following:
"global"
"not_available"
"us"
limit: optional number
Maximum number of time buckets to return in the response.
The default and max limits depend on `bucket_width`: • `"1d"`: Default of 7 days, maximum of 31 days • `"1h"`: Default of 24 hours, maximum of 168 hours • `"1m"`: Default of 60 minutes, maximum of 1440 minutes
models: optional array of string
Restrict usage returned to the specified model(s).
page: optional string
Optionally set to the `next_page` token from the previous response.
service_account_ids: optional array of string
Restrict usage returned to the specified service account ID(s).
service_tiers: optional array of "batch" or "flex" or "flex_discount" or 3 more
Restrict usage returned to the specified service tier(s).
One of the following:
"batch"
"flex"
"flex_discount"
"priority"
"priority_on_demand"
"standard"
speeds: optional array of "fast" or "standard"
Restrict usage returned to the specified speed(s) (Claude Code research preview). Requires the `fast-mode-2026-02-01` beta header.
One of the following:
"fast"
"standard"
workspace_ids: optional array of string
Restrict usage returned to the specified workspace ID(s).
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
MessagesUsageReport object{ data, has_more, next_page }
Get Messages Usage Report
cURL
```python
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"ending_at": "2025-08-02T00:00:00Z",
"results": [
{
"account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 200,
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 500,
"server_tool_use": {
"web_search_requests": 10
},
"service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4",
"service_tier": "standard",
"uncached_input_tokens": 1500,
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2025-08-02T00:00:00Z",
"results": [
{
"account_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"api_key_id": "apikey_01Rj2N8SVvo6BePZj99NhmiT",
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 200,
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 500,
"server_tool_use": {
"web_search_requests": 10
},
"service_account_id": "svac_01Hk3R9TWxq7CfQak00OiVw4",
"service_tier": "standard",
"uncached_input_tokens": 1500,
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
---
## Admin/api-admin-usage-report-retrieve-messages-a10b0b7a1a.md
## Retrieve Messages
**get** `/v1/organizations/usage_report/messages`
Get Messages Usage Report
### Query Parameters
- `starting_at: string`
Time buckets that start on or after this RFC 3339 timestamp will be returned.
Each time bucket will be snapped to the start of the minute/hour/day in UTC.
- `account_ids: optional array of string`
Restrict usage returned to the specified user account ID(s).
- `api_key_ids: optional array of string`
Restrict usage returned to the specified API key ID(s).
- `bucket_width: optional "1d" or "1m" or "1h"`
Time granularity of the response data.
- `"1d"`
- `"1m"`
- `"1h"`
- `context_window: optional array of "0-200k" or "200k-1M"`
Restrict usage returned to the specified context window(s).
- `"0-200k"`
- `"200k-1M"`
- `ending_at: optional string`
Time buckets that end before this RFC 3339 timestamp will be returned.
- `group_by: optional array of "api_key_id" or "workspace_id" or "model" or 6 more`
Group by any subset of the available options. Grouping by `speed` requires the `fast-mode-2026-02-01` beta header.
- `"api_key_id"`
- `"workspace_id"`
- `"model"`
- `"service_tier"`
- `"context_window"`
- `"inference_geo"`
- `"speed"`
- `"account_id"`
- `"service_account_id"`
- `inference_geos: optional array of "global" or "us" or "not_available"`
Restrict usage returned to the specified inference geo(s). Use `not_available` for models that do not support specifying `inference_geo`.
- `"global"`
- `"us"`
- `"not_available"`
- `limit: optional number`
Maximum number of time buckets to return in the response.
The default and max limits depend on `bucket_width`:
• `"1d"`: Default of 7 days, maximum of 31 days
• `"1h"`: Default of 24 hours, maximum of 168 hours
• `"1m"`: Default of 60 minutes, maximum of 1440 minutes
- `models: optional array of string`
Restrict usage returned to the specified model(s).
- `page: optional string`
Optionally set to the `next_page` token from the previous response.
- `service_account_ids: optional array of string`
Restrict usage returned to the specified service account ID(s).
- `service_tiers: optional array of "standard" or "batch" or "priority" or 3 more`
Restrict usage returned to the specified service tier(s).
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `speeds: optional array of "standard" or "fast"`
Restrict usage returned to the specified speed(s) (Claude Code research preview).
Requires the `fast-mode-2026-02-01` beta header.
- `"standard"`
- `"fast"`
- `workspace_ids: optional array of string`
Restrict usage returned to the specified workspace ID(s).
### Header Parameters
- `"anthropic-beta": optional array of string`
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
### Returns
- `MessagesUsageReport = object { data, has_more, next_page }`
- `data: array of object { ending_at, results, starting_at }`
- `ending_at: string`
End of the time bucket (exclusive) in RFC 3339 format.
- `results: array of object { account_id, api_key_id, cache_creation, 10 more }`
List of usage items for this time bucket. There may be multiple items if one or more `group_by[]` parameters are specified.
- `account_id: string`
ID of the user account that made the request. `null` if not grouping by account or for non-OAuth requests.
- `api_key_id: string`
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
- `cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }`
The number of input tokens for cache creation.
- `ephemeral_1h_input_tokens: number`
The number of input tokens used to create the 1 hour cache entry.
- `ephemeral_5m_input_tokens: number`
The number of input tokens used to create the 5 minute cache entry.
- `cache_read_input_tokens: number`
The number of input tokens read from the cache.
- `context_window: "0-200k" or "200k-1M"`
Context window used. `null` if not grouping by context window.
- `"0-200k"`
- `"200k-1M"`
- `inference_geo: string`
Inference geo used matching requests' `inference_geo` parameter if set, otherwise the workspace's `default_inference_geo`.
For models that do not support specifying `inference_geo` the value is `"not_available"`. Always `null` if not grouping by inference geo.
- `model: string`
Model used. `null` if not grouping by model.
- `output_tokens: number`
The number of output tokens generated.
- `server_tool_use: object { web_search_requests }`
Server-side tool usage metrics.
- `web_search_requests: number`
The number of web search requests made.
- `service_account_id: string`
ID of the service account that made the request. `null` if not grouping by service account or for non-OIDC-federation requests.
- `service_tier: "standard" or "batch" or "priority" or 3 more`
Service tier used. `null` if not grouping by service tier.
- `"standard"`
- `"batch"`
- `"priority"`
- `"priority_on_demand"`
- `"flex"`
- `"flex_discount"`
- `uncached_input_tokens: number`
The number of uncached input tokens processed.
- `workspace_id: string`
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
- `starting_at: string`
Start of the time bucket (inclusive) in RFC 3339 format.
- `has_more: boolean`
Indicates if there are more results.
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-3705274a52.md
# Users
## Retrieve
**get** `/v1/organizations/users/{user_id}`
Get User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/users`
List Users
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `email: optional string`
Filter by user email.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of User`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/users/{user_id}`
Update User
### Path Parameters
- `user_id: string`
ID of the User.
### Body Parameters
- `role: "user" or "developer" or "billing" or "claude_code_user"`
New role for the User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"role": "user"
}'
```
## Delete
**delete** `/v1/organizations/users/{user_id}`
Remove User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### User
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### User Delete Response
- `UserDeleteResponse = object { id, type }`
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
---
## Admin/api-admin-users-delete-8ce5cd3878.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fusers%2Fremove)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
List Users
Get User
Update User
Remove User
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Users](/docs/en/api/http/beta/organization/users)
# Remove User
DELETE/v1/organizations/users/{user_id}
Remove a member from the organization.
##### Path parameters
user_id: string
ID of the User.
##### Returns
type: "user_deleted"
Deleted object type.
For Users, this is always `"user_deleted"`.
defaultuser_deleted
id: string
ID of the User.
Remove User
cURL
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user_deleted"
}
```
##### Returns Examples
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
---
## Admin/api-admin-users-delete-fbc1a9c080.md
## Delete
**delete** `/v1/organizations/users/{user_id}`
Remove User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `id: string`
ID of the User.
- `type: "user_deleted"`
Deleted object type.
For Users, this is always `"user_deleted"`.
- `"user_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-f91f4f89c5.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fusers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
Get User
List Users
Update User
Remove User
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Users
##### [Get User](/docs/en/api/http/admin/users/retrieve)
GET/v1/organizations/users/{user_id}
##### [List Users](/docs/en/api/http/admin/users/list)
GET/v1/organizations/users
##### [Update User](/docs/en/api/http/admin/users/update)
POST/v1/organizations/users/{user_id}
##### [Remove User](/docs/en/api/http/admin/users/delete)
DELETE/v1/organizations/users/{user_id}
##### Models
User object{ id, added_at, email, 3 more }
id: string
ID of the User.
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
formatdate-time
email: string
Email of the User.
name: string
Name of the User.
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
"billing"
"claude_code_user"
"developer"
"managed"
"membership_admin"
"owner"
"primary_owner"
"user"
type: "user"
Object type.
For Users, this is always `"user"`.
defaultuser
UserDeleteResponse object{ id, type }
id: string
ID of the User.
type: "user_deleted"
Deleted object type.
For Users, this is always `"user_deleted"`.
---
## Admin/api-admin-users-list-2e0e8109f3.md
## List
**get** `/v1/organizations/users`
List Users
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `email: optional string`
Filter by user email.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of User`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-list-ea56cc7fed.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fusers%2Flist)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
List Users
Get User
Update User
Remove User
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Users](/docs/en/api/http/beta/organization/users)
# List Users
GET/v1/organizations/users
List the organization's members.
##### Query parameters
after_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
email: optional string
Filter by user email.
formatemail
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
roles: optional array of string
Filter to items whose `role` equals one of the supplied values. Repeatable; values are OR'ed together.
Accepted values depend on the organization type: Console and API organizations accept `user`, `developer`, `billing`, `admin`, and `claude_code_user`; Claude Enterprise organizations accept `user`, `owner`, `primary_owner`, `membership_admin`, and `managed`.
##### Returns
data: array of [BetaOrganizationUser](/docs/en/api/http/beta/organization/users#beta_organization_user) { type: "user", id, added_at, 3 more }
type: "user"
Object type.
For Users, this is always `"user"`.
defaultuser
id: string
ID of the User.
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
formatdate-time
email: string
Email of the User.
name: string
Name of the User.
role: [BetaOrganizationRole](/docs/en/api/http/beta/organization#beta_organization_role)
Organization role of the User.
One of the following:
"admin"
"billing"
"claude_code_user"
"developer"
"managed"
"membership_admin"
"owner"
"primary_owner"
"user"
first_id: string or null
First ID in the `data` list. Can be used as the `before_id` for the previous page.
has_more: boolean
Indicates if there are more results in the requested page direction.
last_id: string or null
Last ID in the `data` list. Can be used as the `after_id` for the next page.
List Users
cURL
```python
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"data": [
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"name": "Jane Doe",
"role": "admin",
"type": "user"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
---
## Admin/api-admin-users-retrieve-7965222a69.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fusers%2Fretrieve)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
List Users
Get User
Update User
Remove User
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Users](/docs/en/api/http/beta/organization/users)
# Get User
GET/v1/organizations/users/{user_id}
Retrieve a member of the organization by user ID.
##### Path parameters
user_id: string
ID of the User.
##### Returns
BetaOrganizationUser object{ type: "user", id, added_at, 3 more }
type: "user"
Object type.
For Users, this is always `"user"`.
defaultuser
id: string
ID of the User.
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
formatdate-time
email: string
Email of the User.
name: string
Name of the User.
role: [BetaOrganizationRole](/docs/en/api/http/beta/organization#beta_organization_role)
Organization role of the User.
One of the following:
"admin"
"billing"
"claude_code_user"
"developer"
"managed"
"membership_admin"
"owner"
"primary_owner"
"user"
Get User
cURL
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"name": "Jane Doe",
"role": "admin",
"type": "user"
}
```
##### Returns Examples
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
---
## Admin/api-admin-users-retrieve-ae028818d3.md
## Retrieve
**get** `/v1/organizations/users/{user_id}`
Get User
### Path Parameters
- `user_id: string`
ID of the User.
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-users-update-56bd0224c1.md
## Update
**post** `/v1/organizations/users/{user_id}`
Update User
### Path Parameters
- `user_id: string`
ID of the User.
### Body Parameters
- `role: "user" or "developer" or "billing" or "claude_code_user"`
New role for the User. Cannot be "admin".
- `"user"`
- `"developer"`
- `"billing"`
- `"claude_code_user"`
### Returns
- `User = object { id, added_at, email, 3 more }`
- `id: string`
ID of the User.
- `added_at: string`
RFC 3339 datetime string indicating when the User joined the Organization.
- `email: string`
Email of the User.
- `name: string`
Name of the User.
- `role: "user" or "developer" or "billing" or 2 more`
Organization role of the User.
- `"user"`
- `"developer"`
- `"billing"`
- `"admin"`
- `"claude_code_user"`
- `type: "user"`
Object type.
For Users, this is always `"user"`.
- `"user"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"role": "user"
}'
```
---
## Admin/api-admin-users-update-f0e5dfd352.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fbeta%2Forganization%2Fusers%2Fupdate)
SearchCtrlK
Include beta APIsThe API you’re viewing is only available in beta
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
List Users
Get User
Update User
Remove User
Workspaces
Rate Limits
Compliance Settings
Usage Report
Cost Report
MCP Tunnels
Analytics
Spend Limits
RBAC Groups
RBAC Roles
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
cURL
1. [API reference](/docs/en/api/http)
2. [Beta](/docs/en/api/http/beta)
3. [Organization](/docs/en/api/http/beta/organization)
4. [Users](/docs/en/api/http/beta/organization/users)
# Update User
POST/v1/organizations/users/{user_id}
Update a member's organization role.
##### Path parameters
user_id: string
ID of the User.
##### Body
role: "billing" or "claude_code_user" or "developer" or 2 more
New role for the User.
The accepted values depend on the organization type. Console and API organizations accept `user`, `developer`, `billing`, and `claude_code_user`; `admin` cannot be assigned through the API. Claude Enterprise organizations accept `user` and `managed`.
One of the following:
"billing"
"claude_code_user"
"developer"
"managed"
"user"
##### Returns
BetaOrganizationUser object{ type: "user", id, added_at, 3 more }
type: "user"
Object type.
For Users, this is always `"user"`.
defaultuser
id: string
ID of the User.
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
formatdate-time
email: string
Email of the User.
name: string
Name of the User.
role: [BetaOrganizationRole](/docs/en/api/http/beta/organization#beta_organization_role)
Organization role of the User.
One of the following:
"admin"
"billing"
"claude_code_user"
"developer"
"managed"
"membership_admin"
"owner"
"primary_owner"
"user"
Update User
cURL
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY" \
-d '{
"role": "user"
}'
```
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"name": "Jane Doe",
"role": "admin",
"type": "user"
}
```
##### Returns Examples
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
---
## Admin/api-admin-workspaces-85c02ab620.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Workspaces
##### [Create Workspace](/docs/en/api/http/admin/workspaces/create)
POST/v1/organizations/workspaces
##### [Get Workspace](/docs/en/api/http/admin/workspaces/retrieve)
GET/v1/organizations/workspaces/{workspace_id}
##### [List Workspaces](/docs/en/api/http/admin/workspaces/list)
GET/v1/organizations/workspaces
##### [Update Workspace](/docs/en/api/http/admin/workspaces/update)
POST/v1/organizations/workspaces/{workspace_id}
##### [Archive Workspace](/docs/en/api/http/admin/workspaces/archive)
POST/v1/organizations/workspaces/{workspace_id}/archive
#### Workspaces[Members](/docs/en/api/http/admin/workspaces/members)
##### [Create Workspace Member](/docs/en/api/http/admin/workspaces/members/create)
POST/v1/organizations/workspaces/{workspace_id}/members
##### [Get Workspace Member](/docs/en/api/http/admin/workspaces/members/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [List Workspace Members](/docs/en/api/http/admin/workspaces/members/list)
GET/v1/organizations/workspaces/{workspace_id}/members
##### [Update Workspace Member](/docs/en/api/http/admin/workspaces/members/update)
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [Delete Workspace Member](/docs/en/api/http/admin/workspaces/members/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
#### Workspaces[Rate Limits](/docs/en/api/http/admin/workspaces/rate_limits)
##### [List Workspace Rate Limits](/docs/en/api/http/admin/workspaces/rate_limits/list)
GET/v1/organizations/workspaces/{workspace_id}/rate_limits
#### Workspaces[Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
##### [Create Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/create)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Get Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [List Service Account Workspace Members](/docs/en/api/http/admin/workspaces/service_accounts/list)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Update Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/update)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [Delete Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
---
## Admin/api-admin-workspaces-archive-08df2be86d.md
## Archive
**post** `/v1/organizations/workspaces/{workspace_id}/archive`
Archive Workspace
### Path Parameters
- `workspace_id: string`
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-archive-f0357c972c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Farchive)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Archive Workspace
POST/v1/organizations/workspaces/{workspace_id}/archive
Archive Workspace
##### Path parameters
workspace_id: string
##### Returns
Workspace object{ id, archived_at, compartment_id, 7 more }
Archive Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"name": "Workspace Name",
"tags": {
"env": "prod",
"team": "platform"
},
"type": "workspace"
}
```
##### Returns Examples
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
---
## Admin/api-admin-workspaces-bbad0119fd.md
# Workspaces
## Create
**post** `/v1/organizations/workspaces`
Create Workspace
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration for the workspace. If omitted, defaults to workspace_geo=`"us"`, allowed_inference_geos=`"unrestricted"`, and default_inference_geo=`"global"`.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
- `workspace_geo: optional string`
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}`
Get Workspace
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces`
List Workspaces
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `include_archived: optional boolean`
Whether to include Workspaces that have been archived in the response
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Workspace`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}`
Update Workspace
### Path Parameters
- `workspace_id: string`
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo }`
Data residency configuration for the workspace.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
## Archive
**post** `/v1/organizations/workspaces/{workspace_id}/archive`
Archive Workspace
### Path Parameters
- `workspace_id: string`
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
# Members
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Workspace Member
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Member Delete Response
- `MemberDeleteResponse = object { type, user_id, workspace_id }`
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
# Rate Limits
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-workspaces-create-6061341e22.md
## Create
**post** `/v1/organizations/workspaces`
Create Workspace
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration for the workspace. If omitted, defaults to workspace_geo=`"us"`, allowed_inference_geos=`"unrestricted"`, and default_inference_geo=`"global"`.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
- `workspace_geo: optional string`
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
---
## Admin/api-admin-workspaces-create-d7ce468e9b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Create Workspace
POST/v1/organizations/workspaces
Create Workspace
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
name: string
Name of the Workspace.
maxLength40
minLength1
data_residency: optional object{ allowed_inference_geos, default_inference_geo, workspace_geo } or null
Data residency configuration for the workspace. If omitted, defaults to `workspace_geo: "us"`, `allowed_inference_geos: "unrestricted"`, and `default_inference_geo: "global"`.
allowed_inference_geos: optional array of "global" or "us" or "unrestricted" or null
Permitted inference geo values. Defaults to 'unrestricted' if omitted, which allows all geos. Use the string 'unrestricted' to allow all geos, or a list of specific geos.
One of the following:
array of "global" or "us"
One of the following:
"global"
"us"
"unrestricted"
default_inference_geo: optional "global" or "us" or null
Default inference geo applied when requests omit the parameter. Defaults to 'global' if omitted. Must be a member of `allowed_inference_geos` unless `allowed_inference_geos` is `"unrestricted"`.
One of the following:
"global"
"us"
workspace_geo: optional "us" or null
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
display_color: optional string or null
Hex color code representing the Workspace in the Anthropic Console.
maxLength7
pattern^#\[0-9A-Fa-f\]{6}\$
external_key_id: optional string or null
ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same.
tags: optional map\[string\] or null
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
##### Returns
Workspace object{ id, archived_at, compartment_id, 7 more }
Create Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"name": "x",
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"tags": {
"env": "prod",
"team": "platform"
}
}'
```
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"name": "Workspace Name",
"tags": {
"env": "prod",
"team": "platform"
},
"type": "workspace"
}
```
##### Returns Examples
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
---
## Admin/api-admin-workspaces-list-9a1a726498.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# List Workspaces
GET/v1/organizations/workspaces
List Workspaces
##### Query parameters
after_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
include_archived: optional boolean
Whether to include Workspaces that have been archived in the response
defaultfalse
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
##### Returns
data: array of [Workspace](/docs/en/api/http/$shared#workspace) { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
archived_at: string or null
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
formatdate-time
compartment_id: string
Identifier for this Workspace's encryption compartment. When you configure a customer-managed encryption key (CMEK) on AWS, reference this value in your KMS key-policy condition so the key is scoped to this compartment. On GCP and Azure, Anthropic enforces the compartment binding automatically; you do not need to reference this value in your key configuration. See the CMEK integration guide for the required key configuration; unless your organization is on Claude Platform on AWS, it includes a separate value used during key validation. On Claude Platform on AWS there is no separate validation value: the key is validated against this Workspace's own value when it is attached, so if your key policy uses the compartment condition, add this value to it before attaching the key.
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
formatdate-time
data_residency: object{ allowed_inference_geos, default_inference_geo, workspace_geo }
Data residency configuration.
allowed_inference_geos: array of string or "unrestricted"
Permitted inference geo values. 'unrestricted' means all geos are allowed.
One of the following:
array of string
"unrestricted"
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
external_key_id: string or null
ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same.
name: string
Name of the Workspace.
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
defaultworkspace
first_id: string or null
First ID in the `data` list. Can be used as the `before_id` for the previous page.
has_more: boolean
Indicates if there are more results in the requested page direction.
last_id: string or null
Last ID in the `data` list. Can be used as the `after_id` for the next page.
List Workspaces
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"name": "Workspace Name",
"tags": {
"env": "prod",
"team": "platform"
},
"type": "workspace"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
---
## Admin/api-admin-workspaces-list-db96be5b4c.md
## List
**get** `/v1/organizations/workspaces`
List Workspaces
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `include_archived: optional boolean`
Whether to include Workspaces that have been archived in the response
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of Workspace`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-22e2753d2e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Members
##### [Create Workspace Member](/docs/en/api/http/admin/workspaces/members/create)
POST/v1/organizations/workspaces/{workspace_id}/members
##### [Get Workspace Member](/docs/en/api/http/admin/workspaces/members/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [List Workspace Members](/docs/en/api/http/admin/workspaces/members/list)
GET/v1/organizations/workspaces/{workspace_id}/members
##### [Update Workspace Member](/docs/en/api/http/admin/workspaces/members/update)
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [Delete Workspace Member](/docs/en/api/http/admin/workspaces/members/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### Models
WorkspaceMember object{ type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
defaultworkspace_member
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
MemberDeleteResponse object{ type, user_id, workspace_id }
type: "workspace_member_deleted"
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
defaultworkspace_member_deleted
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
---
## Admin/api-admin-workspaces-members-baf3d594cd.md
# Members
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Workspace Member
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Member Delete Response
- `MemberDeleteResponse = object { type, user_id, workspace_id }`
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
---
## Admin/api-admin-workspaces-members-create-90588f8cea.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Members](/docs/en/api/http/admin/workspaces/members)
# Create Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/members
Create Workspace Member
##### Path parameters
workspace_id: string
ID of the Workspace.
##### Body
user_id: string
ID of the User.
workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"
Role of the new Workspace Member. Cannot be `workspace_billing`.
One of the following:
"workspace_admin"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
##### Returns
WorkspaceMember object{ type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
defaultworkspace_member
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Create Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_admin"
}'
```
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
}
```
##### Returns Examples
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
---
## Admin/api-admin-workspaces-members-create-f4ff1d3a79.md
## Create
**post** `/v1/organizations/workspaces/{workspace_id}/members`
Create Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Body Parameters
- `user_id: string`
ID of the User.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or "workspace_admin"`
Role of the new Workspace Member. Cannot be "workspace_billing".
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_role": "workspace_user"
}'
```
---
## Admin/api-admin-workspaces-members-delete-7ecee4fe03.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Members](/docs/en/api/http/admin/workspaces/members)
# Delete Workspace Member
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Delete Workspace Member
##### Path parameters
workspace_id: string
ID of the Workspace.
user_id: string
ID of the User.
##### Returns
type: "workspace_member_deleted"
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
defaultworkspace_member_deleted
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
Delete Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"type": "workspace_member_deleted",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
```
##### Returns Examples
Response 200
```python
{
"type": "workspace_member_deleted",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
---
## Admin/api-admin-workspaces-members-delete-d0ab41c43a.md
## Delete
**delete** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Delete Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `type: "workspace_member_deleted"`
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
- `"workspace_member_deleted"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-list-4cc8bd7839.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Members](/docs/en/api/http/admin/workspaces/members)
# List Workspace Members
GET/v1/organizations/workspaces/{workspace_id}/members
List Workspace Members
##### Path parameters
workspace_id: string
ID of the Workspace.
##### Query parameters
after_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
before_id: optional string
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
default20
maximum1000
minimum1
##### Returns
data: array of [WorkspaceMember](/docs/en/api/http/admin/workspaces/members#workspaceMember) { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
defaultworkspace_member
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
first_id: string or null
First ID in the `data` list. Can be used as the `before_id` for the previous page.
has_more: boolean
Indicates if there are more results in the requested page direction.
last_id: string or null
Last ID in the `data` list. Can be used as the `after_id` for the next page.
List Workspace Members
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
---
## Admin/api-admin-workspaces-members-list-725de557d8.md
## List
**get** `/v1/organizations/workspaces/{workspace_id}/members`
List Workspace Members
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of WorkspaceMember`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
- `first_id: string`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-retrieve-866558bf94.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Members](/docs/en/api/http/admin/workspaces/members)
# Get Workspace Member
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Get Workspace Member
##### Path parameters
workspace_id: string
ID of the Workspace.
user_id: string
ID of the User.
##### Returns
WorkspaceMember object{ type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
defaultworkspace_member
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Get Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
}
```
##### Returns Examples
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
---
## Admin/api-admin-workspaces-members-retrieve-a68b4bcb12.md
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Get Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-members-update-a03e7cf161.md
## Update
**post** `/v1/organizations/workspaces/{workspace_id}/members/{user_id}`
Update Workspace Member
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
- `user_id: string`
ID of the User.
### Body Parameters
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
New workspace role for the User.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Returns
- `WorkspaceMember = object { type, user_id, workspace_id, workspace_role }`
- `type: "workspace_member"`
Object type.
For Workspace Members, this is always `"workspace_member"`.
- `"workspace_member"`
- `user_id: string`
ID of the User.
- `workspace_id: string`
ID of the Workspace.
- `workspace_role: "workspace_user" or "workspace_developer" or "workspace_restricted_developer" or 2 more`
Role of the Workspace Member.
- `"workspace_user"`
- `"workspace_developer"`
- `"workspace_restricted_developer"`
- `"workspace_admin"`
- `"workspace_billing"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"workspace_role": "workspace_user"
}'
```
---
## Admin/api-admin-workspaces-members-update-deb290fa99.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fmembers%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Create Workspace Member
Get Workspace Member
List Workspace Members
Update Workspace Member
Delete Workspace Member
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Members](/docs/en/api/http/admin/workspaces/members)
# Update Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Update Workspace Member
##### Path parameters
workspace_id: string
ID of the Workspace.
user_id: string
ID of the User.
##### Body
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
New workspace role for the User.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
##### Returns
WorkspaceMember object{ type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
defaultworkspace_member
user_id: string
ID of the User.
workspace_id: string
ID of the Workspace.
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Update Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"workspace_role": "workspace_admin"
}'
```
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
}
```
##### Returns Examples
Response 200
```python
{
"type": "workspace_member",
"user_id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"workspace_role": "workspace_user"
---
## Admin/api-admin-workspaces-rate-limits-1299da20e6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Frate_limits)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
List Workspace Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Rate Limits
##### [List Workspace Rate Limits](/docs/en/api/http/admin/workspaces/rate_limits/list)
GET/v1/organizations/workspaces/{workspace_id}/rate_limits
##### Models
RateLimitListResponse object{ group_type, limits, models, 3 more }
---
## Admin/api-admin-workspaces-rate-limits-7fd15c7aae.md
# Rate Limits
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
## Domain Types
### Rate Limit List Response
- `RateLimitListResponse = object { data, next_page }`
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
---
## Admin/api-admin-workspaces-rate-limits-list-17a31beac0.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Frate_limits%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
List Workspace Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Rate Limits](/docs/en/api/http/admin/workspaces/rate_limits)
# List Workspace Rate Limits
GET/v1/organizations/workspaces/{workspace_id}/rate_limits
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level override. Groups without overrides inherit the organization limits and are not listed; use `GET /v1/organizations/rate_limits` to see those.
When `limit` is omitted, every matching entry is returned in a single page; when `limit` truncates the result, follow `next_page` to fetch the remaining entries.
##### Path parameters
workspace_id: string
The ID of the workspace.
##### Query parameters
group_type: optional "batch" or "files" or "model_group" or 3 more
Filter by group type.
One of the following:
"batch"
"files"
"model_group"
"skills"
"token_count"
"web_search"
limit: optional number
Maximum number of items to return per page. Ranges from `1` to `1000`.
When omitted, every remaining entry is returned in a single page and `next_page` is `null`.
maximum1000
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Returns
data: array of object{ group_type, limits, models, 3 more }
Rate-limit entries for the workspace, one per group that has at least one override.
group_type: "batch" or "files" or "model_group" or 3 more
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
One of the following:
"batch"
"files"
"model_group"
"skills"
"token_count"
"web_search"
limits: array of object{ org_limit, type, value }
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
org_limit: number or null
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
type: string
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
value: number
The workspace-level override value for this limiter type.
models: array of string or null
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
rate_limit_id: string
The `id` of the RateLimit group this override applies to.
type: "workspace_rate_limit"
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
defaultworkspace_rate_limit
workspace_id: string
ID of the Workspace this override applies to.
next_page: string or null
Opaque cursor for the next page of results, or `null` when no entries remain beyond this response.
List Workspace Rate Limits
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"group_type": "batch",
"limits": [
{
"org_limit": 0,
"type": "type",
"value": 0
}
],
"models": [
"string"
],
"rate_limit_id": "rate_limit_id",
"type": "workspace_rate_limit",
"workspace_id": "workspace_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"group_type": "batch",
"limits": [
{
"org_limit": 0,
"type": "type",
"value": 0
}
],
"models": [
"string"
],
"rate_limit_id": "rate_limit_id",
"type": "workspace_rate_limit",
"workspace_id": "workspace_id"
---
## Admin/api-admin-workspaces-rate-limits-list-89661b6ee2.md
## List
**get** `/v1/organizations/workspaces/{workspace_id}/rate_limits`
List rate-limit overrides configured for a workspace.
Returns only the groups and limiter types that have a workspace-level
override. Groups without overrides inherit the organization limits and
are not listed; use `GET /v1/organizations/rate_limits` to see those.
### Path Parameters
- `workspace_id: string`
The ID of the workspace.
### Query Parameters
- `group_type: optional "model_group" or "batch" or "token_count" or 3 more`
Filter by group type.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `page: optional string`
Opaque cursor from a previous response's `next_page`.
### Returns
- `data: array of object { group_type, limits, models, type }`
Rate-limit entries for the workspace, one per group that has at least one override.
- `group_type: "model_group" or "batch" or "token_count" or 3 more`
The kind of rate-limit group this entry represents. `model_group` entries apply to a family of models (listed in `models`); other values apply to an API-surface category and have `models` set to `null`.
- `"model_group"`
- `"batch"`
- `"token_count"`
- `"files"`
- `"skills"`
- `"web_search"`
- `limits: array of object { org_limit, type, value }`
The limiter values overridden for this group in this workspace. Limiter types without a workspace override are omitted and inherit the organization value.
- `org_limit: number`
The organization-level value for the same limiter type, for reference. `null` when the organization has no limit configured for this limiter type.
- `type: string`
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
- `value: number`
The workspace-level override value for this limiter type.
- `models: array of string`
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
- `type: "workspace_rate_limit"`
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
- `"workspace_rate_limit"`
- `next_page: string`
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-retrieve-3dd11b3337.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Get Workspace
GET/v1/organizations/workspaces/{workspace_id}
Get Workspace
##### Path parameters
workspace_id: string
ID of the Workspace.
##### Returns
Workspace object{ id, archived_at, compartment_id, 7 more }
Get Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"name": "Workspace Name",
"tags": {
"env": "prod",
"team": "platform"
},
"type": "workspace"
}
```
##### Returns Examples
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
---
## Admin/api-admin-workspaces-retrieve-e4e9c89d38.md
## Retrieve
**get** `/v1/organizations/workspaces/{workspace_id}`
Get Workspace
### Path Parameters
- `workspace_id: string`
ID of the Workspace.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
---
## Admin/api-admin-workspaces-service-accounts-75c057cb47.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Service Accounts
##### [Create Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/create)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Get Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [List Service Account Workspace Members](/docs/en/api/http/admin/workspaces/service_accounts/list)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Update Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/update)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [Delete Service Account Workspace Member](/docs/en/api/http/admin/workspaces/service_accounts/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### Models
ServiceAccountCreateResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
ServiceAccountRetrieveResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
ServiceAccountUpdateResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
ServiceAccountListResponse object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
ServiceAccountDeleteResponse object{ service_account_id, type, workspace_id }
service_account_id: string
Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op.
type: "service_account_workspace_member_deleted"
defaultservice_account_workspace_member_deleted
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
---
## Admin/api-admin-workspaces-service-accounts-create-27ba3b8a60.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts%2Fcreate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
# Create Service Account Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Add a service account to a workspace with the given `workspace_role`.
The role determines what the service account can do in the workspace and which workspace-scoped permissions it can be granted when authenticating through federation. Every service account is already an implicit `workspace_user` member of the default workspace; adding it explicitly assigns a chosen role. If the service account is already an explicit member of the workspace, its `workspace_role` is replaced with the value supplied here. Archived workspaces return 400. Archived service accounts cannot be added and are rejected.
##### Path parameters
workspace_id: string
ID of the workspace.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
service_account_id: string
Tagged service account ID to add.
workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"
Role to assign to the service account in this workspace.
One of the following:
"workspace_admin"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
##### Returns
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Create Service Account Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"service_account_id": "service_account_id",
"workspace_role": "workspace_admin"
}'
```
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
```
##### Returns Examples
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-workspaces-service-accounts-delete-a469b2ac8c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts%2Fdelete)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
# Delete Service Account Workspace Member
DELETE/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Remove a service account from a workspace.
Removal is idempotent (returns 200 even if the membership was already removed). A DELETE against the implicit default-workspace membership returns 200 but is a no-op and the membership persists; deleting an explicit default-workspace row reverts to the implicit `workspace_user` membership. Archived workspaces return 400.
##### Path parameters
workspace_id: string
ID of the workspace.
service_account_id: string
ID of the service account.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
service_account_id: string
Tagged service account ID (`svac_...`) named in the delete request. Removal is idempotent; see the endpoint description for the implicit-membership no-op.
type: "service_account_workspace_member_deleted"
defaultservice_account_workspace_member_deleted
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
Delete Service Account Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"service_account_id": "service_account_id",
"type": "service_account_workspace_member_deleted",
"workspace_id": "workspace_id"
}
```
##### Returns Examples
Response 200
```python
{
"service_account_id": "service_account_id",
"type": "service_account_workspace_member_deleted",
"workspace_id": "workspace_id"
---
## Admin/api-admin-workspaces-service-accounts-list-09ca8a7d8c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
# List Service Account Workspace Members
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
List the service accounts that are members of a workspace.
Each entry includes the service account's `workspace_role`. Use `limit` and the `next_page` cursor to paginate. Archived workspaces return 400; use `GET /service_accounts/{id}/workspaces` to audit memberships of an archived workspace. The implicit default-workspace membership is not included in this list. Memberships of archived service accounts are omitted from the results.
##### Path parameters
workspace_id: string
ID of the workspace.
##### Query parameters
limit: optional number
Number of results per page.
default20
maximum100
minimum1
page: optional string
Opaque cursor from a previous response's `next_page`.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
data: array of object{ created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
next_page: string or null
Opaque cursor for the next page, or null if no more results.
List Service Account Workspace Members
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-workspaces-service-accounts-retrieve-0c088a31a7.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts%2Fretrieve)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
# Get Service Account Workspace Member
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Retrieve a service account's membership in a workspace.
Returns the membership record, including the service account's `workspace_role` in this workspace. Archived workspaces return 400. For the default workspace, returns the implicit (`implicit: true`) membership when no explicit membership exists; an explicitly added membership is returned with its assigned role. An archived service account returns 404.
##### Path parameters
workspace_id: string
ID of the workspace.
service_account_id: string
ID of the service account.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Returns
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Get Service Account Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"
```
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
```
##### Returns Examples
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-workspaces-service-accounts-update-bf46e42df2.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fservice_accounts%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
Create Service Account Workspace Member
Get Service Account Workspace Member
List Service Account Workspace Members
Update Service Account Workspace Member
Delete Service Account Workspace Member
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
4. [Service Accounts](/docs/en/api/http/admin/workspaces/service_accounts)
# Update Service Account Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
**Requires an OAuth access token with the `org:admin` scope**, from `ant auth login --scope org:admin` or a workload identity federation rule; Admin API keys are not accepted. See [Manage WIF with the Admin API](/docs/en/manage-claude/wif-admin-api).
Change a service account's role in a workspace.
The new `workspace_role` replaces the current one. Only explicit memberships can be updated; to set a role on the implicit default-workspace membership, add the service account explicitly with `POST /workspaces/{workspace_id}/service_accounts`. Archived workspaces return 400. Archived service accounts cannot be updated and are rejected.
##### Path parameters
workspace_id: string
ID of the workspace.
service_account_id: string
ID of the service account.
##### Headers
"anthropic-beta": optional array of string
Optional header to specify the beta version(s) you want to use.
To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.
##### Body
workspace_role: "workspace_admin" or "workspace_developer" or "workspace_restricted_developer" or "workspace_user"
New role for the service account in this workspace.
One of the following:
"workspace_admin"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
##### Returns
created_by_actor_id: string or null
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
implicit: boolean or null
True when this is the implicit default-workspace membership every service account has when no explicit membership exists. Implicit memberships have role `workspace_user` and cannot be removed.
service_account_id: string
Tagged service account ID (`svac_...`).
type: "service_account_workspace_member"
defaultservice_account_workspace_member
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the service account in this workspace. Service accounts cannot hold the `workspace_billing` role.
One of the following:
"workspace_admin"
"workspace_billing"
"workspace_developer"
"workspace_restricted_developer"
"workspace_user"
Update Service Account Workspace Member
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts/$SERVICE_ACCOUNT_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"workspace_role": "workspace_admin"
}'
```
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
}
```
##### Returns Examples
Response 200
```python
{
"created_by_actor_id": "created_by_actor_id",
"implicit": true,
"service_account_id": "service_account_id",
"type": "service_account_workspace_member",
"workspace_id": "workspace_id",
"workspace_role": "workspace_admin"
---
## Admin/api-admin-workspaces-update-44659e11a9.md
## Update
**post** `/v1/organizations/workspaces/{workspace_id}`
Update Workspace
### Path Parameters
- `workspace_id: string`
### Body Parameters
- `name: string`
Name of the Workspace.
- `data_residency: optional object { allowed_inference_geos, default_inference_geo }`
Data residency configuration for the workspace.
- `allowed_inference_geos: optional array of string or "unrestricted"`
Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: optional string`
Default inference geo applied when requests omit the parameter. Must be a member of allowed_inference_geos unless allowed_inference_geos is `"unrestricted"`.
### Returns
- `Workspace = object { id, archived_at, created_at, 4 more }`
- `id: string`
ID of the Workspace.
- `archived_at: string`
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
- `created_at: string`
RFC 3339 datetime string indicating when the Workspace was created.
- `data_residency: object { allowed_inference_geos, default_inference_geo, workspace_geo }`
Data residency configuration.
- `allowed_inference_geos: array of string or "unrestricted"`
Permitted inference geo values. 'unrestricted' means all geos are allowed.
- `UnionMember0 = array of string`
- `UnionMember1 = "unrestricted"`
- `"unrestricted"`
- `default_inference_geo: string`
Default inference geo applied when requests omit the parameter.
- `workspace_geo: string`
Geographic region for workspace data storage. Immutable after creation.
- `display_color: string`
Hex color code representing the Workspace in the Anthropic Console.
- `name: string`
Name of the Workspace.
- `type: "workspace"`
Object type.
For Workspaces, this is always `"workspace"`.
- `"workspace"`
### Example
```http
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY" \
-d '{
"name": "x"
}'
```
---
## Admin/api-admin-workspaces-update-6062dd08a6.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fadmin%2Fworkspaces%2Fupdate)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
Create Workspace
Get Workspace
List Workspaces
Update Workspace
Archive Workspace
Members
Rate Limits
Service Accounts
API Keys
External Keys
Usage Report
Cost Report
Analytics
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Workspaces](/docs/en/api/http/admin/workspaces)
# Update Workspace
POST/v1/organizations/workspaces/{workspace_id}
Update Workspace
##### Path parameters
workspace_id: string
##### Body
data_residency: optional object{ allowed_inference_geos, default_inference_geo } or null
Data residency configuration for the workspace.
allowed_inference_geos: optional array of "global" or "us" or "unrestricted" or null
Permitted inference geo values. Use 'unrestricted' to allow all geos, or a list of specific geos.
One of the following:
array of "global" or "us"
One of the following:
"global"
"us"
"unrestricted"
default_inference_geo: optional "global" or "us" or null
Default inference geo applied when requests omit the parameter. Must be a member of `allowed_inference_geos` unless `allowed_inference_geos` is `"unrestricted"`.
One of the following:
"global"
"us"
display_color: optional string
Hex color code representing the Workspace in the Anthropic Console.
maxLength7
pattern^#\[0-9A-Fa-f\]{6}\$
external_key_id: optional string
ID of the customer-managed encryption key (CMEK) configuration to use for this Workspace. Setting this field requires CMEK to be enabled for your organization. When set, data stored for this Workspace is encrypted with the referenced key. Create key configurations with the External Keys API. On Claude Platform on AWS the value is the AWS KMS key ARN, and the key must be a single-Region key in the same AWS account and Region as the Workspace. On that platform the key is validated against this Workspace when it is attached, so a key-policy problem is reported as an error on this request. This field is write-once: once a key is attached to a Workspace it cannot be detached or replaced. To rotate key material, rotate the underlying key on your cloud KMS; the `external_key_id` stays the same.
name: optional string
Name of the Workspace.
maxLength40
minLength1
tags: optional map\[string\] or null
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
##### Returns
Workspace object{ id, archived_at, compartment_id, 7 more }
Update Workspace
cURL
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-d '{
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"tags": {
"env": "prod",
"team": "platform"
}
}'
```
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"name": "Workspace Name",
"tags": {
"env": "prod",
"team": "platform"
},
"type": "workspace"
}
```
##### Returns Examples
Response 200
```python
{
"id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"archived_at": "2024-11-01T23:59:27.427722Z",
"compartment_id": "f8a7b6c5-4d3e-4f1a-8b9c-0d1e2f3a4b5c",
"created_at": "2024-10-30T23:58:27.427722Z",
"data_residency": {
"allowed_inference_geos": "unrestricted",
"default_inference_geo": "default_inference_geo",
"workspace_geo": "workspace_geo"
},
"display_color": "#6C5BB9",
"external_key_id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
---
## Admin/api-http-admin-analytics-6e54a95b9a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
# Analytics
##### [Get Activity Summaries](/docs/en/api/http/admin/analytics/retrieve_summaries)
GET/v1/organizations/analytics/summaries
##### Models
ActivitySummary object{ summaries }
Response for GET /v1/organizations/analytics/summaries.
AnalyticsUser object{ id, email_address, type }
A user in the organization, identified by tagged id and email address.
id: string
Tagged user identifier (e.g. `user_...`)
email_address: string
Email address of the user
type: "user"
Object type. Always `user`.
defaultuser
AnalyticsUserActor object{ deleted, email, name, 2 more }
deleted: boolean
True when the account has been deleted, or when the user is no longer a member of the organization or its associated organizations (for example, their membership was removed or they were deprovisioned via your identity provider). `email` stays populated for removed users and is null when the account has been deleted. `name` follows the rules described on that field. The `user_id` is still populated for reconciliation.
email: string or null
The user's email address, including for users who are no longer members of the organization or its associated organizations. Null when the account has been deleted (check `deleted`) and for system-minted service accounts, which have no person's mailbox behind them (check `name`).
name: string or null
The user's full name. Null when the user has not set a name. Returns `"Deleted User"` when the account itself has been deleted, or when the user is no longer a member of the organization or its associated organizations and the organization has chosen to hide the names of removed users. Otherwise, the name stays populated for removed users. Rows for system-minted service accounts render the service name (for example, `"Claude Security"` for usage by Anthropic's security-patching service) or null.
type: "user_actor"
Actor type. Always `"user_actor"`.
user_id: string
Tagged user ID.
ConnectorOfficeProductMetrics object{ distinct_session_connector_used_count }
Office Agent activity metrics for a single connector on a given day within one Office product.
distinct_session_connector_used_count: number or null
Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
OfficeProductMetrics object{ connectors_used_count, distinct_connectors_used_count, distinct_session_count, 3 more }
Office Agent activity metrics for a single user on a given day within one Office product.
connectors_used_count: number
Number of MCP connector invocations
distinct_connectors_used_count: number or null
Number of distinct MCP connectors used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
distinct_session_count: number or null
Number of distinct Office Agent sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
distinct_skills_used_count: number or null
Number of distinct skills used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
message_count: number
Number of messages sent
skills_used_count: number
Number of skill invocations
SkillOfficeProductMetrics object{ distinct_session_skill_used_count }
Office Agent activity metrics for a single skill on a given day within one Office product.
distinct_session_skill_used_count: number or null
Number of distinct Office Agent sessions in which the skill was used. A skill counts as used only when it is explicitly activated — the model (or the user, via the skill's slash command) invokes it, reading its instructions into context as part of that activation. Skills that are merely installed or listed as available, or whose content reaches the context without an activation (preloaded, hook-injected, or read as a plain file), are not counted. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
ToolActionCounts object{ accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
rejected_count: number
Number of tool proposals rejected
#### Analytics[Usage](/docs/en/api/http/admin/analytics/usage)
##### [Get Token Usage Over Time](/docs/en/api/http/admin/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
##### [Get Per-User Token Usage](/docs/en/api/http/admin/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
#### Analytics[Cost](/docs/en/api/http/admin/analytics/cost)
##### [Get Cost Over Time](/docs/en/api/http/admin/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
##### [Get Per-User Cost](/docs/en/api/http/admin/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
#### Analytics[Users](/docs/en/api/http/admin/analytics/users)
##### [List User Activity](/docs/en/api/http/admin/analytics/users/list)
GET/v1/organizations/analytics/users
#### Analytics[Skills](/docs/en/api/http/admin/analytics/skills)
##### [Get Skill Usage](/docs/en/api/http/admin/analytics/skills/list)
GET/v1/organizations/analytics/skills
#### Analytics[Connectors](/docs/en/api/http/admin/analytics/connectors)
##### [Get Connector Usage](/docs/en/api/http/admin/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
#### Analytics[Chat Projects](/docs/en/api/http/admin/analytics/chat_projects)
##### [Get Chat Project Usage](/docs/en/api/http/admin/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
#### Analytics[Plugins](/docs/en/api/http/admin/analytics/plugins)
##### [Get Plugin Usage](/docs/en/api/http/admin/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
#### Analytics[Artifacts](/docs/en/api/http/admin/analytics/artifacts)
##### [Get Artifact Activity](/docs/en/api/http/admin/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
---
## Admin/api-http-admin-analytics-artifacts-6f54fc6d3f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fartifacts)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Get Artifact Activity
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Artifacts
##### [Get Artifact Activity](/docs/en/api/http/admin/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
##### Models
ArtifactUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/artifacts.
`next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints.
---
## Admin/api-http-admin-analytics-artifacts-list-93531c6be2.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fartifacts%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Get Artifact Activity
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Artifacts](/docs/en/api/http/admin/analytics/artifacts)
# Get Artifact Activity
GET/v1/organizations/analytics/artifacts
Get artifact-creation activity for a given day, broken out by MIME type.
Returns the full (`artifact_type`, `is_shared`) cube for the organization; `next_page` is null except for grouped queries, which paginate. The cube can be broken out per product, per member, or per RBAC group via `group_by[]`, and scoped via `filter[]`. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: string
UTC date in YYYY-MM-DD format. The day to get artifact activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `artifact_type`, `is_shared`, `product`, `rbac_group_id`, `user_id`. Value forms: `artifact_type` is a canonical artifact MIME type (e.g. `text/markdown`) or `other`; `is_shared` is `true` or `false`; `product` is `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by: `product`, `user_id` and/or `rbac_group_id`. The ungrouped artifact-type cube is finite and returned in full; grouped queries multiply the cube and paginate via `next_page`. `product` takes the values `chat`, `claude_code`, or `cowork` (the surfaces that create artifacts). `rbac_group_id` attributes a user to every group they held at any point during the requested UTC day, so grouped rows are not an exclusive partition. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Maximum rows to return (1-1000, default 100). The ungrouped artifact-type cube is finite and returned in full; `limit` is the page size only when `group_by[]` multiplies the cube.
minimum1
maximum1000
page: optional string
Opaque cursor from a previous response's `next_page` field. Only valid with `group_by[]` — the ungrouped cube is never paginated.
##### Returns
ArtifactUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/artifacts.
`next_page` is null on ungrouped queries — the artifact-type cube is finite and returned in full. Grouped queries (`group_by[]` on `product` / `user_id` / `rbac_group_id`) multiply the cube and paginate like the other analytics list endpoints.
Get Artifact Activity
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/artifacts \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"artifact_type": "artifact_type",
"artifacts_created_count": 0,
"distinct_user_count": 0,
"is_shared": true,
"published_artifacts_created_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"artifact_type": "artifact_type",
"artifacts_created_count": 0,
"distinct_user_count": 0,
"is_shared": true,
"published_artifacts_created_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-http-admin-analytics-chat-projects-0af5e99d82.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fchat_projects)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Get Chat Project Usage
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Chat Projects
##### [Get Chat Project Usage](/docs/en/api/http/admin/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
##### Models
ChatProjectUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
---
## Admin/api-http-admin-analytics-chat-projects-list-17eae8956c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fchat_projects%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Get Chat Project Usage
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Chat Projects](/docs/en/api/http/admin/analytics/chat_projects)
# Get Chat Project Usage
GET/v1/organizations/analytics/apps/chat/projects
Get per-project activity for a given day, with cursor-based pagination.
Returns activity metrics for each project in the organization, sorted by project ID. Use `group_by[]` to break projects out per member or per RBAC group, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get project activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
ChatProjectUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
Get Chat Project Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"distinct_user_count": 0,
"message_count": 0,
"project_id": "project_id",
"project_name": "project_name",
"created_at": "2019-12-27T18:11:19.117Z",
"created_by": {
"id": "id",
"email_address": "email_address",
"type": "user"
},
"distinct_conversation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"distinct_user_count": 0,
"message_count": 0,
"project_id": "project_id",
"project_name": "project_name",
"created_at": "2019-12-27T18:11:19.117Z",
"created_by": {
"id": "id",
"email_address": "email_address",
"type": "user"
},
"distinct_conversation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-http-admin-analytics-connectors-084a7e6747.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fconnectors)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Get Connector Usage
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Connectors
##### [Get Connector Usage](/docs/en/api/http/admin/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
##### Models
ConnectorUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/connectors.
---
## Admin/api-http-admin-analytics-connectors-list-24a65287c9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fconnectors%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Get Connector Usage
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Connectors](/docs/en/api/http/admin/analytics/connectors)
# Get Connector Usage
GET/v1/organizations/analytics/connectors
Get per-connector usage for a given day, with cursor-based pagination.
Returns connector usage metrics for the organization, sorted by connector name. Connector names are normalized from their various sources — for example, "Atlassian MCP server" and "mcp-atlassian" both appear as "atlassian". Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get connector usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `connector_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `connector_name` matches case-insensitively, a display name such as 'GitHub MCP' also matches its normalized stored form ('github'), and for rows whose `connector_name` is an opaque connector id the connector's display name (`connector_display_name`) also matches; `product` is one of `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
ConnectorUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/connectors.
Get Connector Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/connectors \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_connector_used_count": 0
},
"claude_code_metrics": {
"distinct_session_connector_used_count": 0
},
"connector_name": "connector_name",
"cowork_metrics": {
"distinct_session_connector_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_connector_used_count": 0
},
"outlook": {
"distinct_session_connector_used_count": 0
},
"powerpoint": {
"distinct_session_connector_used_count": 0
},
"word": {
"distinct_session_connector_used_count": 0
}
},
"connector_display_name": "connector_display_name",
"individual_auth_distinct_user_count": 0,
"managed_auth_distinct_user_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"read_call_count": 0,
"unclassified_call_count": 0,
"user_id": "user_id",
"write_call_count": 0
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_connector_used_count": 0
},
"claude_code_metrics": {
"distinct_session_connector_used_count": 0
},
"connector_name": "connector_name",
"cowork_metrics": {
"distinct_session_connector_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_connector_used_count": 0
},
"outlook": {
"distinct_session_connector_used_count": 0
},
"powerpoint": {
"distinct_session_connector_used_count": 0
},
"word": {
"distinct_session_connector_used_count": 0
}
},
"connector_display_name": "connector_display_name",
"individual_auth_distinct_user_count": 0,
"managed_auth_distinct_user_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-http-admin-analytics-cost-d0c7e0382d.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fcost)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Cost
##### [Get Cost Over Time](/docs/en/api/http/admin/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
##### [Get Per-User Cost](/docs/en/api/http/admin/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
##### Models
CostBucket object{ data, data_refreshed_at, has_more, 2 more }
UserCost object{ data, data_refreshed_at, has_more, 2 more }
---
## Admin/api-http-admin-analytics-cost-list-by-user-d287c2e561.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fcost%2Flist_by_user)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Cost](/docs/en/api/http/admin/analytics/cost)
# Get Per-User Cost
GET/v1/organizations/analytics/user_cost_report
Get per-user cost in USD across a date range.
Returns one row per user, ranked by spend. Use this to see which users account for the most cost. Only cost attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/cost_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range.
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
exclude_deleted_users: optional boolean
If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual.
defaultfalse
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more
Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/cost_report` endpoint. The `product`, `model`, `context_window`, `inference_geo`, and `speed` dimensions — and the time bucket, when `bucket_width` is set — count toward `limit`. `cost_type` and `token_type` do not: `cost_type` returns one row per cost component (tokens, web search, code execution); `token_type` returns one row per token type, each with `cost_type: "tokens"`; combining both returns the per-token-type rows plus the web-search and code-execution rows. A page can therefore contain more rows than `limit` when `cost_type` or `token_type` is requested.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"cost_type"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
"token_type"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it.
default20
maximum1000
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
defaultdesc
One of the following:
"asc"
"desc"
order_by: optional "amount" or "list_amount"
Metric to rank actors by. Defaults to `amount`.
defaultamount
One of the following:
"amount"
"list_amount"
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UserCost object{ data, data_refreshed_at, has_more, 2 more }
Get Per-User Cost
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"amount": "41280.000000",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"list_amount": "51600.000000",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"amount": "41280.000000",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"list_amount": "51600.000000",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-http-admin-analytics-cost-list-f0a5b6ab26.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fcost%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Get Cost Over Time
Get Per-User Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Cost](/docs/en/api/http/admin/analytics/cost)
# Get Cost Over Time
GET/v1/organizations/analytics/cost_report
Get cost in USD over time across a date range.
Returns cost bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, speed, cost type, or token type. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
default1d
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 8 more
Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"cost_type"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
"token_type"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256).
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
CostBucket object{ data, data_refreshed_at, has_more, 2 more }
Get Cost Over Time
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"amount": "amount",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"amount": "amount",
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "claude-opus-5",
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"token_type": "cache_creation.ephemeral_1h_input_tokens"
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-http-admin-analytics-plugins-5b2afe090e.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fplugins)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Get Plugin Usage
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Plugins
##### [Get Plugin Usage](/docs/en/api/http/admin/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
##### Models
PluginUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/plugins.
---
## Admin/api-http-admin-analytics-plugins-list-512d01e20b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fplugins%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Get Plugin Usage
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Plugins](/docs/en/api/http/admin/analytics/plugins)
# Get Plugin Usage
GET/v1/organizations/analytics/plugins
Get per-plugin install + invocation usage for a given day, with pagination.
Returns plugin usage metrics for the organization across Cowork and Claude Code, sorted by plugin name. The `plugin_name` value `third-party` is an aggregate bucket, not a plugin: it collects plugin activity, from either surface, for which the reporting client did not provide a plugin name — so an organization's own plugins can contribute both to their own named rows and to this bucket. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface (Cowork / Claude Code), and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Requires an API key with the `read:analytics` scope. `starting_date` / `ending_date` select range-rollup mode like `/skills`.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get plugin usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `plugin_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `plugin_name` matches case-insensitively; `product` is `claude_code` or `cowork` (the only surfaces with plugin attribution); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. On this endpoint `product` takes the values `claude_code` or `cowork` only (the surfaces with plugin attribution). Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
PluginUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/plugins.
Get Plugin Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/plugins \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"claude_code_metrics": {
"distinct_session_plugin_used_count": 0
},
"cowork_metrics": {
"distinct_session_plugin_used_count": 0
},
"distinct_user_count": 0,
"install_count": 0,
"invocation_count": 0,
"plugin_name": "plugin_name",
"plugin_id": "plugin_id",
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"claude_code_metrics": {
"distinct_session_plugin_used_count": 0
},
"cowork_metrics": {
"distinct_session_plugin_used_count": 0
},
"distinct_user_count": 0,
"install_count": 0,
"invocation_count": 0,
"plugin_name": "plugin_name",
"plugin_id": "plugin_id",
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
---
## Admin/api-http-admin-analytics-retrieve-summaries-79a424b965.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fretrieve_summaries)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Get Activity Summaries
GET/v1/organizations/analytics/summaries
Get organization-wide activity summaries for a date range.
Returns one entry per day from `starting_date` (inclusive) to `ending_date` (exclusive). Data is typically available with a 1-day lag and may be revised by a few percent over the following days: when `ending_date` is omitted it defaults to the most recent available day + 1, so the last entry covers the most recent available day. The series can be scoped to an RBAC group via `filter[]=rbac_group_id:{id}`. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_date: string
UTC date in YYYY-MM-DD format. Start of the date range (inclusive). Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive). Data is typically available with a 1-day lag, so this can be at most today — which is also the default when omitted, making the last entry cover the most recent available day. Data may be revised by a few percent over the following days. The range may span at most 366 days.
formatdate
filter: optional array of string
Filters as `dimension:value`. Only `rbac_group_id` is supported (e.g. `filter[]=rbac_group_id:{id}`); repeat the param to OR across groups. Scopes the whole day series to members of the matching group(s), re-aggregated from member-level activity — org-wide seat/invite fields and the adoption rates derived from them are null on scoped rows. `rbac_group_id` accepts the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each UTC day (time-of-usage attribution). At most 100 entries.
maxItems100
##### Returns
ActivitySummary object{ summaries }
Response for GET /v1/organizations/analytics/summaries.
Get Activity Summaries
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/summaries \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"summaries": [
{
"assigned_seat_count": 0,
"cowork_daily_active_user_count": 0,
"cowork_monthly_active_user_count": 0,
"cowork_weekly_active_user_count": 0,
"daily_active_user_count": 0,
"daily_adoption_rate": 0,
"ending_at": "2019-12-27T18:11:19.117Z",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "2019-12-27T18:11:19.117Z",
"weekly_active_user_count": 0,
"weekly_adoption_rate": 0,
"chat_daily_active_user_count": 0,
"chat_monthly_active_user_count": 0,
"chat_weekly_active_user_count": 0,
"claude_code_daily_active_user_count": 0,
"claude_code_monthly_active_user_count": 0,
"claude_code_weekly_active_user_count": 0,
"claude_design_daily_active_user_count": 0,
"claude_design_monthly_active_user_count": 0,
"claude_design_weekly_active_user_count": 0,
"office_agent_daily_active_user_count": 0,
"office_agent_monthly_active_user_count": 0,
"office_agent_weekly_active_user_count": 0,
"science_daily_active_user_count": 0,
"science_entitled_user_count": 0,
"science_monthly_active_user_count": 0,
"science_weekly_active_user_count": 0
}
]
}
```
##### Returns Examples
Response 200
```python
{
"summaries": [
{
"assigned_seat_count": 0,
"cowork_daily_active_user_count": 0,
"cowork_monthly_active_user_count": 0,
"cowork_weekly_active_user_count": 0,
"daily_active_user_count": 0,
"daily_adoption_rate": 0,
"ending_at": "2019-12-27T18:11:19.117Z",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "2019-12-27T18:11:19.117Z",
"weekly_active_user_count": 0,
"weekly_adoption_rate": 0,
"chat_daily_active_user_count": 0,
"chat_monthly_active_user_count": 0,
"chat_weekly_active_user_count": 0,
"claude_code_daily_active_user_count": 0,
"claude_code_monthly_active_user_count": 0,
"claude_code_weekly_active_user_count": 0,
"claude_design_daily_active_user_count": 0,
"claude_design_monthly_active_user_count": 0,
"claude_design_weekly_active_user_count": 0,
"office_agent_daily_active_user_count": 0,
"office_agent_monthly_active_user_count": 0,
"office_agent_weekly_active_user_count": 0,
"science_daily_active_user_count": 0,
"science_entitled_user_count": 0,
"science_monthly_active_user_count": 0,
"science_weekly_active_user_count": 0
---
## Admin/api-http-admin-analytics-skills-6c4e5150f5.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fskills)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Get Skill Usage
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Skills
##### [Get Skill Usage](/docs/en/api/http/admin/analytics/skills/list)
GET/v1/organizations/analytics/skills
##### Models
SkillUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/skills.
---
## Admin/api-http-admin-analytics-skills-list-3908cc16a7.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fskills%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
Skills
Get Skill Usage
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Skills](/docs/en/api/http/admin/analytics/skills)
# Get Skill Usage
GET/v1/organizations/analytics/skills
Get per-skill usage for a given day, with cursor-based pagination.
Returns skill usage metrics for the organization, sorted by skill name. Use `group_by[]` to break usage out per member, per RBAC group, or per product surface, and `filter[]` to scope results; the parameter descriptions list the supported dimensions. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get skill usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `product`, `rbac_group_id`, `share_status`, `skill_name`, `user_id`. Value forms: `product` is one of `chat`, `claude_code`, `cowork`, or `office_agent`; `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `share_status` is one of `organization`, `private`, or `public`; `skill_name` matches case-insensitively; `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "product" or "rbac_group_id" or "user_id"
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
One of the following:
"product"
"rbac_group_id"
"user_id"
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
SkillUsage object{ data, next_page }
Response for GET /v1/organizations/analytics/skills.
Get Skill Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/skills \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_skill_used_count": 0
},
"claude_code_metrics": {
"distinct_session_skill_used_count": 0
},
"cowork_metrics": {
"distinct_session_skill_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_skill_used_count": 0
},
"outlook": {
"distinct_session_skill_used_count": 0
},
"powerpoint": {
"distinct_session_skill_used_count": 0
},
"word": {
"distinct_session_skill_used_count": 0
}
},
"skill_name": "skill_name",
"attributed_list_price": "attributed_list_price",
"currency": "USD",
"enable_count": 0,
"estimated_overage_spend": "estimated_overage_spend",
"invocation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"share_status": "organization",
"skill_display_name": "skill_display_name",
"user_id": "user_id"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"distinct_conversation_skill_used_count": 0
},
"claude_code_metrics": {
"distinct_session_skill_used_count": 0
},
"cowork_metrics": {
"distinct_session_skill_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_skill_used_count": 0
},
"outlook": {
"distinct_session_skill_used_count": 0
},
"powerpoint": {
"distinct_session_skill_used_count": 0
},
"word": {
"distinct_session_skill_used_count": 0
}
},
"skill_name": "skill_name",
"attributed_list_price": "attributed_list_price",
"currency": "USD",
"enable_count": 0,
"estimated_overage_spend": "estimated_overage_spend",
"invocation_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"share_status": "organization",
"skill_display_name": "skill_display_name",
---
## Admin/api-http-admin-analytics-usage-5c69bf8dbe.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fusage)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Usage
##### [Get Token Usage Over Time](/docs/en/api/http/admin/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
##### [Get Per-User Token Usage](/docs/en/api/http/admin/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
##### Models
UsageBucket object{ data, data_refreshed_at, has_more, 2 more }
UserUsage object{ data, data_refreshed_at, has_more, 2 more }
---
## Admin/api-http-admin-analytics-usage-list-8d33319656.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fusage%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Usage](/docs/en/api/http/admin/analytics/usage)
# Get Token Usage Over Time
GET/v1/organizations/analytics/usage_report
Get token usage over time across a date range.
Returns token usage bucketed by minute, hour, or day, optionally broken down by product, model, context window, inference region, or speed. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
default1d
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more
Dimensions to break each time bucket out by. Defaults to no grouping (one total per bucket). Each bucket reports at most its top 100 groups; a group beyond that cap has no row in that bucket (there is no remainder row), so grouped buckets are not exhaustive when a dimension has more than 100 distinct values.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Maximum number of time buckets per page. Defaults and caps vary by `bucket_width` (`1d`: default 7, max 31; `1h`: default 24, max 168; `1m`: default 60, max 256).
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UsageBucket object{ data, data_refreshed_at, has_more, 2 more }
Get Token Usage Over Time
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 0,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 0,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"uncached_input_tokens": 0
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 0,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 0,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"uncached_input_tokens": 0
}
],
"starting_at": "2019-12-27T18:11:19.117Z"
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-http-admin-analytics-usage-list-by-user-3b894b2695.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fusage%2Flist_by_user)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Get Token Usage Over Time
Get Per-User Token Usage
Cost
Users
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Usage](/docs/en/api/http/admin/analytics/usage)
# Get Per-User Token Usage
GET/v1/organizations/analytics/user_usage_report
Get per-user token usage across a date range.
Returns one row per user, ranked by the chosen token metric. Use this to see which users consume the most tokens. Only usage attributable to a seat user is included; for organization-wide totals including direct API-key and automation traffic, use the bucketed `/v1/organizations/analytics/usage_report` endpoint. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
starting_at: string
Start of range, inclusive. RFC 3339 tz-aware. Must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.
formatdate-time
bucket_width: optional "1d" or "1h" or "1m"
Time-bucket granularity. When set, each row's `starting_at` and `ending_at` are populated and one actor may span several rows (one per time bucket with usage). The time bucket counts toward `limit`, so one page can return multiple rows for the same actor. `ending_at` is required when `bucket_width` is set, and with `bucket_width="1m"` the range may span at most 24 hours. When omitted, each row aggregates the full `[starting_at, ending_at)` range.
One of the following:
"1d"
"1h"
"1m"
claude_tag_categories: optional array of "dm" or "engaged" or "monitoring" or 2 more
Filter to Claude Tag (Claude in Slack) usage in specific spend categories. Usage with no category never matches. `dm` usage is reported under the user's product rather than `claude-tag`, so combining this filter with `products[]=claude-tag` excludes it. Use `group_by[]=claude_tag_category` to break out per-category values.
maxItems100
One of the following:
"dm"
"engaged"
"monitoring"
"proactive"
"scheduled"
claude_tag_user_ids: optional array of string
Filter to Claude Tag (Claude in Slack) usage attributed to specific Slack users, by Slack user ID (for example `U0123ABCDEF`), not claude.ai user ID. Usage that is not Claude Tag, and Claude Tag usage not attributed to a single user, never matches. Use `group_by[]=claude_tag_user_id` to break out per-user values.
maxItems100
context_windows: optional array of "0-200k" or "200k-1M"
Filter to specific context-window pricing tiers. Use `group_by[]=context_window` to break out per-tier values.
maxItems100
One of the following:
"0-200k"
"200k-1M"
ending_at: optional string
End of range, exclusive. When omitted, defaults to the earlier of now and `starting_at` + 31 days. The range may span at most 31 days.
formatdate-time
exclude_deleted_users: optional boolean
If true, omit rows for users who are deleted (`deleted: true`). A page may contain fewer than `limit` rows; use `has_more` and `next_page` to paginate as usual.
defaultfalse
group_by: optional array of "claude_tag_category" or "claude_tag_user_id" or "context_window" or 6 more
Break each actor's row out by the given dimensions. Accepts the same values as the bucketed `/usage_report` endpoint. `limit` bounds (actor × time bucket × dimension) rows — with dimensions or `bucket_width` present, one actor may span several rows.
maxItems100
One of the following:
"claude_tag_category"
"claude_tag_user_id"
"context_window"
"inference_geo"
"model"
"product"
"rbac_group_id"
"slack_channel_id"
"speed"
inference_geos: optional array of "global" or "not_available" or "us"
Filter to specific inference regions. `not_available` matches rows where the region is unset. Use `group_by[]=inference_geo` to break out per-region values.
maxItems100
One of the following:
"global"
"not_available"
"us"
limit: optional number
Number of rows per page (1-1000, default 20). One row per actor unless `group_by[]` or `bucket_width` splits an actor across rows; `cost_type`/`token_type` fan-out rows (cost endpoint only) are the exception — they do not count toward this limit, so `data` can exceed it.
default20
maximum1000
minimum1
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
maxItems100
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
defaultdesc
One of the following:
"asc"
"desc"
order_by: optional "output_tokens" or "requests" or "total_tokens" or "uncached_input_tokens"
Metric to rank actors by. Defaults to `total_tokens`.
defaulttotal_tokens
One of the following:
"output_tokens"
"requests"
"total_tokens"
"uncached_input_tokens"
page: optional string
Opaque cursor from a previous response's `next_page` field.
products: optional array of "chat" or "claude-tag" or "claude_code" or 4 more
Product surfaces to include. Defaults to all products.
maxItems100
One of the following:
"chat"
"claude-tag"
"claude_code"
"claude_design"
"claude_in_chrome"
"cowork"
"office_agent"
rbac_group_ids: optional array of string
Filter to usage attributed to specific RBAC groups. Accepts tagged RBAC group IDs (`rbac_group_...`) or bare group UUIDs. A row matches when the user belonged to any of the listed groups on the (UTC) day the usage occurred; usage with no group attribution never matches.
maxItems100
slack_channel_ids: optional array of string
Filter to usage originating from specific Slack channels. Use `group_by[]=slack_channel_id` to break out per-channel values.
maxItems100
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
maxItems100
One of the following:
"fast"
"standard"
user_ids: optional array of string
Filter to specific users by tagged user ID.
maxItems100
##### Returns
UserUsage object{ data, data_refreshed_at, has_more, 2 more }
Get Per-User Token Usage
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 891000,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"total_tokens": 5377000,
"uncached_input_tokens": 1284500
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor",
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"claude_tag_category": "dm",
"claude_tag_user_id": "U0123ABCDEF",
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "claude-opus-5",
"output_tokens": 891000,
"product": "chat",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"slack_channel_id": "C0123ABCDEF",
"speed": "fast",
"starting_at": "2019-12-27T18:11:19.117Z",
"total_tokens": 5377000,
"uncached_input_tokens": 1284500
}
],
"data_refreshed_at": "2019-12-27T18:11:19.117Z",
"has_more": true,
"next_page": "next_page",
"organization_id": "org_013FP9SaFPBg7Kw7fetjn6cF"
---
## Admin/api-http-admin-analytics-users-60fb3229e9.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fusers)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
List User Activity
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
# Users
##### [List User Activity](/docs/en/api/http/admin/analytics/users/list)
GET/v1/organizations/analytics/users
##### Models
UserActivity object{ data, next_page }
Response for GET /v1/organizations/analytics/users.
---
## Admin/api-http-admin-analytics-users-list-23bec50d22.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fapi%2Fhttp%2Fadmin%2Fanalytics%2Fusers%2Flist)
SearchCtrlK
Include beta APIs
Using the API
[Features overview](/docs/en/api/overview)[Beta headers](/docs/en/api/beta-headers)[Errors](/docs/en/api/errors)
Messages
Create a Message
Count tokens in a Message
Batches
Managed Agents
Agents
Environments
Sessions
Deployments
Deployment Runs
Vaults
Memory Stores
Dreams
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Models
List Models
Get a Model
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
Organization
Get Current Organization
API Keys
External Keys
Federation
Invites
Service Accounts
Users
Workspaces
Rate Limits
Compliance Settings
Tunnels
Create Tunnel
Get Tunnel
List Tunnels
Archive Tunnel
Reveal Tunnel Token
Rotate Tunnel Token
Certificates
User Profiles
Create User Profile
List User Profiles
Get User Profile
Update User Profile
Create Enrollment URL
Webhooks
Unwrap
Parse Unverified
Admin
Organizations
Invites
Users
RBAC Groups
RBAC Roles
Workspaces
API Keys
External Keys
Usage Report
Cost Report
Analytics
Get Activity Summaries
Usage
Cost
Users
List User Activity
Skills
Connectors
Chat Projects
Plugins
Artifacts
Spend Limits
Rate Limits
Service Accounts
Federation Issuers
Federation Rules
MCP Tunnels
Compliance API
Activities
Organizations
Groups
Apps
Code
Completions
Create a Text Completion
Support & configuration
[Rate limits](/docs/en/api/rate-limits)[Service tiers](/docs/en/api/service-tiers)[IAM actions (Claude Platform on AWS)](/docs/en/api/claude-platform-on-aws-iam-actions)[Versions](/docs/en/api/versioning)[IP addresses](/docs/en/api/ip-addresses)[Supported regions](/docs/en/api/supported-regions)
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
[Console](/)
Copy page
1. [API reference](/docs/en/api/http)
2. [Admin](/docs/en/api/http/admin)
3. [Analytics](/docs/en/api/http/admin/analytics)
4. [Users](/docs/en/api/http/admin/analytics/users)
# List User Activity
GET/v1/organizations/analytics/users
Get per-user activity for a given day, with cursor-based pagination.
Returns activity metrics for each user in the organization, sorted by email address. Use `group_by[]` for per-RBAC-group aggregates, or `filter[]` to scope results to specific members, groups, or a chat project. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query parameters
date: optional string
UTC date in YYYY-MM-DD format. The day to get user activity for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
ending_date: optional string
UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
formatdate
filter: optional array of string
Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `project_id`, `rbac_group_id`, `user_id`. Value forms: `project_id` takes a tagged project id (`claude_proj_...`) and scopes each member's row to their claude.ai chat activity within that project (it cannot be combined with `group_by[]` or an `rbac_group_id` filter); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
maxItems100
group_by: optional array of "rbac_group_id"
Dimensions to break results out by (e.g. `group_by[]=rbac_group_id`). Supported on this endpoint: `rbac_group_id`. Rows are already per-member, so the one supported grouping aggregates them per RBAC group instead. Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
maxItems100
limit: optional number
Number of results per page (1-1000, default 100).
minimum1
maximum1000
order: optional "asc" or "desc"
Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.
One of the following:
"asc"
"desc"
order_by: optional string
Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
page: optional string
Opaque cursor from a previous response's `next_page` field.
starting_date: optional string
UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
formatdate
##### Returns
UserActivity object{ data, next_page }
Response for GET /v1/organizations/analytics/users.
List User Activity
cURL
```python
curl https://api.anthropic.com/v1/organizations/analytics/users \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_ADMIN_API_KEY"
```
Response 200
```python
{
"data": [
{
"chat_metrics": {
"connectors_used_count": 0,
"distinct_artifacts_created_count": 0,
"distinct_connectors_used_count": 0,
"distinct_conversation_count": 0,
"distinct_files_uploaded_count": 0,
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_shared_artifacts_viewed_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"shared_conversations_viewed_count": 0,
"thinking_message_count": 0
},
"claude_code_metrics": {
"core_metrics": {
"artifacts_created_count": 0,
"commit_count": 0,
"distinct_session_count": 0,
"lines_of_code": {
"added_count": 0,
"removed_count": 0
},
"pull_request_count": 0
},
"tool_actions": {
"edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"multi_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"notebook_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"write_tool": {
"accepted_count": 0,
"rejected_count": 0
}
}
},
"cowork_metrics": {
"action_count": 0,
"artifacts_created_count": 0,
"connectors_used_count": 0,
"dispatch_turn_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0,
"distinct_plugins_used_count": 0,
"edit_tool_count": 0,
"file_edit_count": 0,
"multi_edit_tool_count": 0,
"notebook_edit_tool_count": 0,
"plugins_used_count": 0,
"sessions_with_file_edits_count": 0,
"write_tool_count": 0
},
"design_metrics": {
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_session_count": 0,
"message_count": 0
},
"office_metrics": {
"excel": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"outlook": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"powerpoint": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"word": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
}
},
"science_metrics": {
"delegation_count": 0,
"distinct_session_count": 0,
"message_count": 0,
"remote_compute_job_count": 0,
"skills_used_count": 0
},
"web_search_count": 0,
"distinct_user_count": 0,
"last_activity_date": "2019-12-27",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user": {
"id": "id",
"email_address": "email_address",
"type": "user"
}
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"chat_metrics": {
"connectors_used_count": 0,
"distinct_artifacts_created_count": 0,
"distinct_connectors_used_count": 0,
"distinct_conversation_count": 0,
"distinct_files_uploaded_count": 0,
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_shared_artifacts_viewed_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"shared_conversations_viewed_count": 0,
"thinking_message_count": 0
},
"claude_code_metrics": {
"core_metrics": {
"artifacts_created_count": 0,
"commit_count": 0,
"distinct_session_count": 0,
"lines_of_code": {
"added_count": 0,
"removed_count": 0
},
"pull_request_count": 0
},
"tool_actions": {
"edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"multi_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"notebook_edit_tool": {
"accepted_count": 0,
"rejected_count": 0
},
"write_tool": {
"accepted_count": 0,
"rejected_count": 0
}
}
},
"cowork_metrics": {
"action_count": 0,
"artifacts_created_count": 0,
"connectors_used_count": 0,
"dispatch_turn_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0,
"distinct_plugins_used_count": 0,
"edit_tool_count": 0,
"file_edit_count": 0,
"multi_edit_tool_count": 0,
"notebook_edit_tool_count": 0,
"plugins_used_count": 0,
"sessions_with_file_edits_count": 0,
"write_tool_count": 0
},
"design_metrics": {
"distinct_projects_created_count": 0,
"distinct_projects_used_count": 0,
"distinct_session_count": 0,
"message_count": 0
},
"office_metrics": {
"excel": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"outlook": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"powerpoint": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
},
"word": {
"connectors_used_count": 0,
"distinct_connectors_used_count": 0,
"distinct_session_count": 0,
"distinct_skills_used_count": 0,
"message_count": 0,
"skills_used_count": 0
}
},
"science_metrics": {
"delegation_count": 0,
"distinct_session_count": 0,
"message_count": 0,
"remote_compute_job_count": 0,
"skills_used_count": 0
},
"web_search_count": 0,
"distinct_user_count": 0,
"last_activity_date": "2019-12-27",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user": {
"id": "id",
"email_address": "email_address",
---
## Agents-Tools/agents-and-tools-agent-skills-best-practices-d1da876439.md
# Skill authoring best practices
Learn how to write effective Skills that Claude can discover and use successfully.
---
Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
For conceptual background on how Skills work, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Core principles
### Concise is key
The [context window](/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
- The system prompt
- Conversation history
- Other Skills' metadata
- Your actual request
Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
**Default assumption:** Claude is already very smart
Only add context Claude doesn't already have. Challenge each piece of information:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
**Good example: Concise** (approximately 50 tokens):
````markdown
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad example: Too verbose** (approximately 150 tokens):
```markdown
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
The concise version assumes Claude knows what PDFs are and how libraries work.
### Set appropriate degrees of freedom
Match the level of specificity to the task's fragility and variability.
**High freedom** (text-based instructions):
Use when:
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach
Example:
```markdown
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```
**Medium freedom** (pseudocode or scripts with parameters):
Use when:
- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior
Example:
````markdown
## Generate report
Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
```
````
**Low freedom** (specific scripts, few or no parameters):
Use when:
- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed
Example:
````markdown
## Database migration
Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```
Do not modify the command or add additional flags.
````
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
- **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
### Test with all models you plan to use
Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.
**Testing considerations by model:**
- **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
- **Claude Sonnet** (balanced): Is the Skill clear and efficient?
- **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.
## Skill structure
<Note>
**YAML Frontmatter:** The SKILL.md frontmatter requires two fields:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
- Should describe what the Skill does and when to use it
For complete Skill structure details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
</Note>
### Naming conventions
Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
Remember that the `name` field must use lowercase letters, numbers, and hyphens only.
**Good naming examples (gerund form):**
- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`
**Acceptable alternatives:**
- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`
**Avoid:**
- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection
Consistent naming makes it easier to:
- Reference Skills in documentation and conversations
- Understand what a Skill does at a glance
- Organize and search through multiple Skills
- Maintain a professional, cohesive skill library
### Writing effective descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
<Warning>
**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
- **Good:** "Processes Excel files and generates reports"
- **Avoid:** "I can help you process Excel files"
- **Avoid:** "You can use this to process Excel files"
</Warning>
**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
Effective examples:
**PDF Processing skill:**
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Excel Analysis skill:**
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```yaml
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
Avoid vague descriptions like these:
```yaml
description: Helps with documents
```
```yaml
description: Processes data
```
```yaml
description: Does stuff with files
```
### Progressive disclosure patterns
SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
**Practical guidance:**
- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the patterns below to organize instructions, code, and resources effectively
#### Visual overview: From simple to complex
A basic Skill starts with just a SKILL.md file containing metadata and instructions:
As your Skill grows, you can bundle additional content that Claude loads only when needed:
The complete Skill directory structure might look like this:
```text
pdf/
├── SKILL.md # Main instructions (loaded when triggered)
├── FORMS.md # Form-filling guide (loaded as needed)
├── reference.md # API reference (loaded as needed)
├── examples.md # Usage examples (loaded as needed)
└── scripts/
├── analyze_form.py # Utility script (executed, not loaded)
├── fill_form.py # Form filling script
└── validate.py # Validation script
```
#### Pattern 1: High-level guide with references
````markdown
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
````
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
#### Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
```text
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
```
````markdown SKILL.md
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
````
#### Pattern 3: Conditional details
Show basic content, link to advanced content:
```markdown
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
### Avoid deeply nested references
Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
**Bad example: Too deep**:
```markdown
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
```
**Good example: One level deep**:
```markdown
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```
### Structure longer reference files with table of contents
For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
**Example:**
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
## Core methods
...
```
Claude can then read the complete file or jump to specific sections as needed.
For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below.
## Workflows and feedback loops
### Use workflows for complex tasks
Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
**Example 1: Research synthesis workflow** (for Skills without code):
````markdown
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
````
This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi-step process.
**Example 2: PDF form filling workflow** (for Skills with code):
````markdown
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```
**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
This extracts form fields and their locations, saving to `fields.json`.
**Step 2: Create field mapping**
Edit `fields.json` to add values for each field.
**Step 3: Validate mapping**
Run: `python scripts/validate_fields.py fields.json`
Fix any validation errors before continuing.
**Step 4: Fill the form**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify output**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
````
Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows.
### Implement feedback loops
**Common pattern:** Run validator → fix errors → repeat
This pattern greatly improves output quality.
**Example 1: Style guide compliance** (for Skills without code):
```markdown
## Content review process
1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
- Check terminology consistency
- Verify examples follow the standard format
- Confirm all required sections are present
3. If issues found:
- Note each issue with specific section reference
- Revise the content
- Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document
```
This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE_GUIDE.md, and Claude performs the check by reading and comparing.
**Example 2: Document editing process** (for Skills with code):
```markdown
## Document editing process
1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
```
The validation loop catches errors early.
## Content guidelines
### Avoid time-sensitive information
Don't include information that will become outdated:
**Bad example: Time-sensitive** (will become wrong):
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good example** (use "old patterns" section):
```markdown
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
The old patterns section provides historical context without cluttering the main content.
### Use consistent terminology
Choose one term and use it throughout the Skill:
**Good - Consistent:**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad - Inconsistent:**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
Consistency helps Claude understand and follow instructions.
## Common patterns
### Template pattern
Provide templates for output format. Match the level of strictness to your needs.
**For strict requirements** (like API responses or data formats):
````markdown
## Report structure
ALWAYS use this exact template structure:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
````
**For flexible guidance** (when adaptation is useful):
````markdown
## Report structure
Here is a sensible default format, but use your best judgment based on the analysis:
```markdown
# [Analysis Title]
## Executive summary
[Overview]
## Key findings
[Adapt sections based on what you discover]
## Recommendations
[Tailor to the specific context]
```
Adjust sections as needed for the specific analysis type.
````
### Examples pattern
For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
````markdown
## Commit message format
Generate commit messages following these examples:
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling
- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```
Follow this style: type(scope): brief description, then detailed explanation.
````
Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
### Conditional workflow pattern
Guide Claude through decision points:
```markdown
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
```
<Tip>
If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
</Tip>
## Evaluation and iteration
### Build evaluations first
**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.
**Evaluation-driven development:**
1. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context
2. **Create evaluations:** Build three scenarios that test these gaps
3. **Establish baseline:** Measure Claude's performance without the Skill
4. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations
5. **Iterate:** Execute evaluations, compare against baseline, and refine
This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
**Evaluation structure:**
```json
{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
"Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
"Extracts text content from all pages in the document without missing any pages",
"Saves the extracted text to a file named output.txt in a clear, readable format"
]
}
```
<Note>
This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
</Note>
### Develop Skills iteratively with Claude
The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
**Creating a new Skill:**
1. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
2. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.
**Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns.
3. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
<Tip>
Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it generates properly structured SKILL.md content with appropriate frontmatter and body content.
</Tip>
4. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
5. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
6. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
7. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
**Iterating on existing Skills:**
The same hierarchical pattern continues when improving Skills. You alternate between:
- **Working with Claude A** (the expert who helps refine the Skill)
- **Testing with Claude B** (the agent using the Skill to perform real work)
- **Observing Claude B's behavior** and bringing insights back to Claude A
1. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios
2. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices
**Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
3. **Return to Claude A for improvements:** Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
4. **Review Claude A's suggestions:** Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section.
5. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
6. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
**Gathering team feedback:**
1. Share Skills with teammates and observe their usage
2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
3. Incorporate feedback to address blind spots in your own usage patterns
**Why this approach works:** Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
### Observe how Claude navigates Skills
As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
- **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
## Anti-patterns to avoid
### Avoid Windows-style paths
Always use forward slashes in file paths, even on Windows:
- ✓ **Good:** `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid:** `scripts\helper.py`, `reference\guide.md`
Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
### Avoid offering too many options
Don't present multiple approaches unless necessary:
````markdown
**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
````
## Advanced: Skills with executable code
The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills).
### Solve, don't punt
When writing scripts for Skills, handle error conditions rather than punting to Claude.
**Good example: Handle errors explicitly:**
```python nocheck
def process_file(path):
"""Process a file, creating it if it doesn't exist."""
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
# Create file with default content instead of failing
print(f"File {path} not found, creating default")
with open(path, "w") as f:
f.write("")
return ""
except PermissionError:
# Provide alternative instead of failing
print(f"Cannot access {path}, using default")
return ""
```
**Bad example: Punt to Claude:**
```python nocheck
def process_file(path):
# Just fail and let Claude figure it out
return open(path).read()
```
Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
**Good example: Self-documenting:**
```python nocheck
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```
**Bad example: Magic numbers:**
```python nocheck
TIMEOUT = 47 # Why 47?
RETRIES = 5 # Why 5?
```
### Provide utility scripts
Even if Claude could write a script, pre-made scripts offer advantages:
**Benefits of utility scripts:**
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses
The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
**Important distinction:** Make clear in your instructions whether Claude should:
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
For most utility scripts, execution is preferred because it's more reliable and efficient. See the [Runtime environment](#runtime-environment) section below for details on how script execution works.
**Example:**
````markdown
## Utility scripts
**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
Output format:
```json
{
"field_name": {"type": "text", "x": 100, "y": 200},
"signature": {"type": "sig", "x": 150, "y": 500}
}
```
**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```
**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
````
### Use visual analysis
When inputs can be rendered as images, have Claude analyze them:
````markdown
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
````
<Note>
In this example, you'd need to write the `pdf_to_images.py` script.
</Note>
Claude's vision capabilities help understand layouts and structures.
### Create verifiable intermediate outputs
When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
**Solution:** Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
**Why this pattern works:**
- **Catches errors early:** Validation finds problems before changes are applied
- **Machine-verifiable:** Scripts provide objective verification
- **Reversible planning:** Claude can iterate on the plan without touching originals
- **Clear debugging:** Error messages point to specific problems
**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
**Implementation tip:** Make validation scripts verbose with specific error messages like "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues.
### Package dependencies
Skills run in the code execution environment with platform-specific limitations:
- **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories
- **Claude API:** Has no network access and no runtime package installation
List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool).
### Runtime environment
Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/docs/en/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
**How this affects your authoring:**
**How Claude accesses Skills:**
1. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. **Files read on-demand:** Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
3. **Scripts executed efficiently:** Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
4. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read
- **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
- **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
- **Organize for discovery:** Structure directories by domain or feature
- Good: `reference/finance.md`, `reference/sales.md`
- Bad: `docs/file1.md`, `docs/file2.md`
- **Bundle comprehensive resources:** Include complete API docs, extensive examples, large datasets; no context penalty until accessed
- **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code
- **Make execution intent clear:**
- "Run `analyze_form.py` to extract fields" (execute)
- "See `analyze_form.py` for the extraction algorithm" (read as reference)
- **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests
**Example:**
```text
bigquery-skill/
├── SKILL.md (overview, points to reference files)
└── reference/
├── finance.md (revenue metrics)
├── sales.md (pipeline data)
└── product.md (usage analytics)
```
When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
For complete details on the technical architecture, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
### MCP tool references
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
**Format:** `ServerName:tool_name`
**Example:**
```markdown
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
```
Where:
- `BigQuery` and `GitHub` are MCP server names
- `bigquery_schema` and `create_issue` are the tool names within those servers
Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
### Avoid assuming tools are installed
Don't assume packages are available:
````markdown
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
````
## Technical notes
### YAML frontmatter requirements
The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules:
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1024 characters, non-empty, no XML tags
See the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
### Token budgets
Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
## Checklist for effective Skills
Before sharing a Skill, verify:
### Core quality
- [ ] Description is specific and includes key terms
- [ ] Description includes both what the Skill does and when to use it
- [ ] SKILL.md body is under 500 lines
- [ ] Additional details are in separate files (if needed)
- [ ] No time-sensitive information (or in "old patterns" section)
- [ ] Consistent terminology throughout
- [ ] Examples are concrete, not abstract
- [ ] File references are one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
### Code and scripts
- [ ] Scripts solve problems rather than punt to Claude
- [ ] Error handling is explicit and helpful
- [ ] No "voodoo constants" (all values justified)
- [ ] Required packages listed in instructions and verified as available
- [ ] Scripts have clear documentation
- [ ] No Windows-style paths (all forward slashes)
- [ ] Validation/verification steps for critical operations
- [ ] Feedback loops included for quality-critical tasks
### Testing
- [ ] At least three evaluations created
- [ ] Tested with Haiku, Sonnet, and Opus
- [ ] Tested with real usage scenarios
- [ ] Team feedback incorporated (if applicable)
## Next steps
<CardGroup cols={2}>
<Card
title="Get started with Agent Skills"
icon="rocket"
href="/docs/en/agents-and-tools/agent-skills/quickstart"
>
Create your first Skill
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Create and manage Skills in Claude Code
</Card>
<Card
title="Use Skills with the API"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Upload and use Skills programmatically
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-best-practices-ee885bfc4c.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fbest-practices)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Skills
# Skill authoring best practices
Copy page
Learn how to write effective Skills that Claude can discover and use successfully.
Copy page
Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
For conceptual background on how Skills work, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Core principles
### Concise is key
The [context window](/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
- The system prompt
- Conversation history
- Other Skills' metadata
- Your actual request
Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
**Default assumption:** Claude is already very smart
Only add context Claude doesn't already have. Challenge each piece of information:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
**Good example: Concise** (approximately 50 tokens):
```` shiki
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad example: Too verbose** (approximately 150 tokens):
```python
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
The concise version assumes Claude already has information about PDFs and how libraries work.
### Set appropriate degrees of freedom
Match the level of specificity to the task's fragility and variability.
**High freedom** (text-based instructions):
Use when:
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach
Example:
```python
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```
**Medium freedom** (pseudocode or scripts with parameters):
Use when:
- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior
Example:
```` shiki
## Generate report
Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
```
````
**Low freedom** (specific scripts, few or no parameters):
Use when:
- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed
Example:
```` shiki
## Database migration
Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```
Do not modify the command or add additional flags.
````
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
- **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
### Test with all models you plan to use
Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.
**Testing considerations by model:**
- **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
- **Claude Sonnet** (balanced): Is the Skill clear and efficient?
- **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.
## Skill structure
**YAML Frontmatter:** The SKILL.md frontmatter requires two fields:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1,024 characters
- Cannot contain XML tags
- Should describe what the Skill does and when to use it
For complete Skill structure details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
### Naming conventions
Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
Remember that the `name` field must use lowercase letters, numbers, and hyphens only.
**Good naming examples (gerund form):**
- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`
**Acceptable alternatives:**
- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`
**Avoid:**
- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection
Consistent naming makes it easier to:
- Reference Skills in documentation and conversations
- Understand what a Skill does at a glance
- Organize and search through multiple Skills
- Maintain a professional, cohesive skill library
### Writing effective descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
- **Good:** "Processes Excel files and generates reports"
- **Avoid:** "I can help you process Excel files"
- **Avoid:** "You can use this to process Excel files"
**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
Effective examples:
**PDF Processing skill:**
```python
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Excel Analysis skill:**
```python
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```python
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
Avoid vague descriptions like these:
```python
description: Helps with documents
```
```python
description: Processes data
```
```python
description: Does stuff with files
```
### Progressive disclosure patterns
SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
**Practical guidance:**
- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the following patterns to organize instructions, code, and resources effectively
#### Visual overview: From simple to complex
A basic Skill starts with just a SKILL.md file containing metadata and instructions:
As your Skill grows, you can bundle additional content that Claude loads only when needed:
The complete Skill directory structure might look like this:
- `pdf/`
- `SKILL.md`: Main instructions (loaded when triggered)
- `FORMS.md`: Form-filling guide (loaded as needed)
- `reference.md`: API reference (loaded as needed)
- `examples.md`: Usage examples (loaded as needed)
- `scripts/`
- `analyze_form.py`: Utility script (executed, not loaded)
- `fill_form.py`: Form filling script
- `validate.py`: Validation script
#### Pattern 1: High-level guide with references
```` shiki
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
````
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
#### Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
- `bigquery-skill/`
- `SKILL.md` (overview and navigation)
- `reference/`
- `finance.md` (revenue, billing metrics)
- `sales.md` (opportunities, pipeline)
- `product.md` (API usage, features)
- `marketing.md` (campaigns, attribution)
SKILL.md
```` shiki
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
````
#### Pattern 3: Conditional details
Show basic content, link to advanced content:
```python
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
### Avoid deeply nested references
Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
**Bad example: Too deep**:
```python
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
```
**Good example: One level deep**:
```python
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```
### Structure longer reference files with table of contents
For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
**Example:**
```python
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
## Core methods
...
```
Claude can then read the complete file or jump to specific sections as needed.
For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section later in this guide.
## Workflows and feedback loops
### Use workflows for complex tasks
Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
**Example 1: Research synthesis workflow** (for Skills without code):
```` shiki
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
````
This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multistep process.
**Example 2: PDF form filling workflow** (for Skills with code):
```` shiki
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```
**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
This extracts form fields and their locations, saving to `fields.json`.
**Step 2: Create field mapping**
Edit `fields.json` to add values for each field.
**Step 3: Validate mapping**
Run: `python scripts/validate_fields.py fields.json`
Fix any validation errors before continuing.
**Step 4: Fill the form**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify output**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
````
Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multistep workflows.
### Implement feedback loops
**Common pattern:** Run validator → fix errors → repeat
This pattern greatly improves output quality.
**Example 1: Style guide compliance** (for Skills without code):
```python
## Content review process
1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
- Check terminology consistency
- Verify examples follow the standard format
- Confirm all required sections are present
3. If issues found:
- Note each issue with specific section reference
- Revise the content
- Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document
```
This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE_GUIDE.md, and Claude performs the check by reading and comparing.
**Example 2: Document editing process** (for Skills with code):
```python
## Document editing process
1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
```
The validation loop catches errors early.
## Content guidelines
### Avoid time-sensitive information
Don't include information that will become outdated:
**Bad example: Time-sensitive** (will become wrong):
```python
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good example** (use "old patterns" section):
```python
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
```
The old patterns section provides historical context without cluttering the main content.
### Use consistent terminology
Choose one term and use it throughout the Skill:
**Good - Consistent:**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad - Inconsistent:**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
Consistency helps Claude parse and follow instructions.
## Common patterns
### Template pattern
Provide templates for output format. Match the level of strictness to your needs.
**For strict requirements** (such as API responses or data formats):
```` shiki
## Report structure
ALWAYS use this exact template structure:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
````
**For flexible guidance** (when adaptation is useful):
```` shiki
## Report structure
Here is a sensible default format, but use your best judgment based on the analysis:
```markdown
# [Analysis Title]
## Executive summary
[Overview]
## Key findings
[Adapt sections based on what you discover]
## Recommendations
[Tailor to the specific context]
```
Adjust sections as needed for the specific analysis type.
````
### Examples pattern
For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
```` shiki
## Commit message format
Generate commit messages following these examples:
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling
- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```
Follow this style: type(scope): brief description, then detailed explanation.
````
Examples convey the desired style and level of detail to Claude more clearly than descriptions alone.
### Conditional workflow pattern
Guide Claude through decision points:
```python
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
```
If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
## Evaluation and iteration
### Build evaluations first
**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.
**Evaluation-driven development:**
1. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context
2. **Create evaluations:** Build three scenarios that test these gaps
3. **Establish baseline:** Measure Claude's performance without the Skill
4. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations
5. **Iterate:** Execute evaluations, compare against baseline, and refine
This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
**Evaluation structure:**
```python
{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
"Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
"Extracts text content from all pages in the document without missing any pages",
"Saves the extracted text to a file named output.txt in a clear, readable format"
]
}
```
This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
### Develop Skills iteratively with Claude
The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
**Creating a new Skill:**
1. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
2. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.
**Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as "always exclude test accounts"), and common query patterns.
3. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it generates properly structured SKILL.md content with appropriate frontmatter and body content.
4. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
5. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
6. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
7. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
**Iterating on existing Skills:**
The same hierarchical pattern continues when improving Skills. You alternate between:
- **Working with Claude A** (the expert who helps refine the Skill)
- **Testing with Claude B** (the agent using the Skill to perform real work)
- **Observing Claude B's behavior** and bringing insights back to Claude A
1. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios
2. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices
**Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
3. **Return to Claude A for improvements:** Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
4. **Review Claude A's suggestions:** Claude A might suggest reorganizing to make rules more prominent, using stronger language such as "MUST filter" instead of "always filter," or restructuring the workflow section.
5. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
6. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
**Gathering team feedback:**
1. Share Skills with teammates and observe their usage
2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
3. Incorporate feedback to address gaps in your own usage patterns
**Why this approach works:** Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
### Observe how Claude navigates Skills
As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
- **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
## Anti-patterns to avoid
### Avoid Windows-style paths
Always use forward slashes in file paths, even on Windows:
- [x] **Good:** `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid:** `scripts\helper.py`, `reference\guide.md`
Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
### Avoid offering too many options
Don't present multiple approaches unless necessary:
```` shiki
**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
````
## Advanced: Skills with executable code
The following sections focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills).
### Solve, don't defer
When writing scripts for Skills, handle error conditions rather than deferring to Claude.
**Good example: Handle errors explicitly:**
```python
def process_file(path):
"""Process a file, creating it if it doesn't exist."""
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
# Create file with default content instead of failing
print(f"File {path} not found, creating default")
with open(path, "w") as f:
f.write("")
return ""
except PermissionError:
# Provide alternative instead of failing
print(f"Cannot access {path}, using default")
return ""
```
**Bad example: Defer to Claude:**
```python
def process_file(path):
# Just fail and let Claude figure it out
return open(path).read()
```
Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
**Good example: Self-documenting:**
```python
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```
**Bad example: Magic numbers:**
```python
TIMEOUT = 47 # Why 47?
RETRIES = 5 # Why 5?
```
### Provide utility scripts
Even if Claude could write a script, pre-made scripts offer advantages:
**Benefits of utility scripts:**
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses
The preceding diagram shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
**Important distinction:** Make clear in your instructions whether Claude should:
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
For most utility scripts, execution is preferred because it's more reliable and efficient. See the following [Runtime environment](#runtime-environment) section for details on how script execution works.
**Example:**
```` shiki
## Utility scripts
**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
Output format:
```json
{
"field_name": {"type": "text", "x": 100, "y": 200},
"signature": {"type": "sig", "x": 150, "y": 500}
}
```
**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```
**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
````
### Use visual analysis
When inputs can be rendered as images, have Claude analyze them:
```` shiki
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
````
In this example, you'd need to write the `pdf_to_images.py` script.
Claude's vision capabilities help analyze layouts and structures.
### Create verifiable intermediate outputs
When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
**Solution:** Use the workflow pattern shown earlier (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
**Why this pattern works:**
- **Catches errors early:** Validation finds problems before changes are applied
- **Machine-verifiable:** Scripts provide objective verification
- **Reversible planning:** Claude can iterate on the plan without touching originals
- **Clear debugging:** Error messages point to specific problems
**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
**Implementation tip:** Make validation scripts verbose with specific error messages such as "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues.
### Package dependencies
Skills run in the code execution environment with platform-specific limitations:
- **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories
- **Claude API:** Has no network access and no runtime package installation
List required packages in your SKILL.md and verify they're available in the [Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation.
### Runtime environment
Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/docs/en/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
**How this affects your authoring:**
**How Claude accesses Skills:**
1. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. **Files read on-demand:** Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
3. **Scripts executed efficiently:** Utility scripts can be executed through bash without loading their full contents into context. Only the script's output consumes tokens
4. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read
- **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
- **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
- **Organize for discovery:** Structure directories by domain or feature
- Good: `reference/finance.md`, `reference/sales.md`
- Bad: `docs/file1.md`, `docs/file2.md`
- **Bundle comprehensive resources:** Include complete API docs, extensive examples, large datasets; no context penalty until accessed
- **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code
- **Make execution intent clear:**
- "Run `analyze_form.py` to extract fields" (execute)
- "See `analyze_form.py` for the extraction algorithm" (read as reference)
- **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests
**Example:**
- `bigquery-skill/`
- `SKILL.md` (overview, points to reference files)
- `reference/`
- `finance.md` (revenue metrics)
- `sales.md` (pipeline data)
- `product.md` (usage analytics)
When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and calls bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
For complete details on the technical architecture, see [How Skills work](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
### MCP tool references
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
**Format:** `ServerName:tool_name`
**Example:**
```python
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
```
Where:
- `BigQuery` and `GitHub` are MCP server names
- `bigquery_schema` and `create_issue` are the tool names within those servers
Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
### Avoid assuming tools are installed
Don't assume packages are available:
```python
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
```
## Technical notes
### YAML frontmatter requirements
The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules:
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1,024 characters, non-empty, no XML tags
See the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
### Token budgets
Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
## Checklist for effective Skills
Before sharing a Skill, verify:
### Core quality
- Description is specific and includes key terms
- Description includes both what the Skill does and when to use it
- SKILL.md body is under 500 lines
- Additional details are in separate files (if needed)
- No time-sensitive information (or in "old patterns" section)
- Consistent terminology throughout
- Examples are concrete, not abstract
- File references are one level deep
- Progressive disclosure used appropriately
- Workflows have clear steps
### Code and scripts
- Scripts solve problems rather than defer to Claude
- Error handling is explicit and helpful
- No "voodoo constants" (all values justified)
- Required packages listed in instructions and verified as available
- Scripts have clear documentation
- No Windows-style paths (all forward slashes)
- Validation/verification steps for critical operations
- Feedback loops included for quality-critical tasks
### Testing
- At least three evaluations created
- Tested with Haiku, Sonnet, and Opus
- Tested with real usage scenarios
- Team feedback incorporated (if applicable)
## Next steps
[Get started with Agent Skills](/docs/en/agents-and-tools/agent-skills/quickstart)
Create your first Skill
[Use Skills in Claude Code](https://code.claude.com/docs/en/skills)
Create and manage Skills in Claude Code
[Use Skills with the API](/docs/en/build-with-claude/skills-guide)
Upload and use Skills programmatically
---
## Agents-Tools/agents-and-tools-agent-skills-enterprise-552d8d9221.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fenterprise)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Skills
# Skills for enterprise
Copy page
Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
Copy page
This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Security review and vetting
Deploying Skills in an enterprise requires answering two distinct questions:
1. **Are Skills safe in general?** See the [security considerations](/docs/en/agents-and-tools/agent-skills/overview#security-considerations) section in the overview for platform-level security details.
2. **How do I vet a specific Skill?** Use the following risk assessment and review checklist.
### Risk tier assessment
Evaluate each Skill against these risk indicators before approving deployment:
| Risk indicator | What to look for | Concern level |
|--------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| Code execution | Scripts in the Skill directory (`*.py`, `*.sh`, `*.js`) | High: scripts run with full environment access |
| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude's behavior conditionally | High: can bypass security controls |
| MCP server references | Instructions referencing MCP tools (`ServerName:tool_name`) | High: extends access beyond the Skill itself |
| Network access patterns | URLs, API endpoints, `fetch`, `curl`, or `requests` calls | High: potential data exfiltration vector |
| Hardcoded credentials | API keys, tokens, or passwords in Skill files or scripts | High: secrets exposed in Git history and context window |
| Filesystem access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: may access unintended data |
| Tool invocations | Instructions directing Claude to use bash, file operations, or other tools | Medium: review what operations are performed |
### Review checklist
Before deploying any Skill from a third party or internal contributor, complete these steps:
1. **Read all Skill directory content.** Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
2. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.
3. **Check for adversarial instructions.** Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.
4. **Check for external URL fetches or network calls.** Search scripts and instructions for network access patterns (`http`, `requests.get`, `urllib`, `curl`, `fetch`).
5. **Verify no hardcoded credentials.** Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.
6. **Identify tools and commands the Skill instructs Claude to invoke.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
7. **Confirm redirect destinations.** If the Skill references external URLs, verify they point to expected domains.
8. **Verify no data exfiltration patterns.** Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.
Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to execute arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.
### Skill content scanning
Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. After you turn on **Skill and plugin security scanning** at [claude.ai \> Organization settings \> Skills](https://claude.ai/admin-settings/skills), Skills that members then upload or edit in claude.ai or Cowork are scanned for signs of malicious behavior, such as hidden code execution, sending your data to an outside service, or instructions that tamper with Claude's safeguards. A Skill that fails the scan, or whose scan hasn't finished, is blocked from use. A Skill that passes with a warning stays usable behind a caution notice. If scanning is available to your organization, turn it on. It complements, but doesn't replace, the [review checklist](#review-checklist).
Scanning doesn't cover the Claude API. Skills you upload through the Skills API (`/v1/skills`), including from the Claude Console, aren't scanned, so for API deployments, rely on the review checklist and [version pinning](#versioning-strategy). Scanning also doesn't apply to Skills that were already in your organization when you turned it on, or to organizations with certain data handling configurations, such as customer-managed encryption keys (CMEK), zero data retention (ZDR), or HIPAA readiness. For setup steps, exclusions, and result types, see [Get started with skill and plugin scanning](https://support.claude.com/en/articles/15927065-get-started-with-skill-and-plugin-scanning) in the Claude Help Center.
## Evaluating Skills before deployment
Skills can degrade agent performance if they trigger incorrectly, conflict with other Skills, or provide poor instructions. Require evaluation before any production deployment.
### What to evaluate
Establish approval gates for these dimensions before deploying any Skill:
| Dimension | What it measures | Example failure |
|-----------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Triggering accuracy | Does the Skill activate for the right queries and stay inactive for unrelated ones? | Skill triggers on every spreadsheet mention, even when the user just wants to discuss data |
| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don't exist in its directory |
| Coexistence | Does adding this Skill degrade other Skills? | New Skill's description is too broad, stealing triggers from existing Skills |
| Instruction following | Does Claude follow the Skill's instructions accurately? | Claude skips validation steps or uses wrong libraries |
| Output quality | Does the Skill produce correct, useful results? | Generated reports have formatting errors or missing data |
### Evaluation requirements
Require Skill authors to submit evaluation suites with 3–5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), because Skill effectiveness varies by model.
For detailed guidance on building evaluations, see [evaluation and iteration](/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](/docs/en/test-and-evaluate/develop-tests).
### Using evaluations for lifecycle decisions
Evaluation results signal when to act:
- **Declining trigger accuracy:** Update the Skill's description or instructions
- **Coexistence conflicts:** Consolidate overlapping Skills or narrow descriptions
- **Consistently low output quality:** Rewrite instructions or add validation steps
- **Persistent failures across updates:** Deprecate the Skill
## Skill lifecycle management
1. 1
### Plan
Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
2. 2
### Create and review
Ensure the Skill author follows [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). Require a security review using the [review checklist](#review-checklist). Require an evaluation suite before approval. Establish separation of duties: Skill authors should not be their own reviewers.
3. 3
### Test
Require evaluations in isolation (Skill alone) and alongside existing Skills (coexistence testing). Verify triggering accuracy, output quality, and absence of regressions across your active Skill set before approving for production.
4. 4
### Deploy
Upload through the Skills API for workspace-wide access. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
5. 5
### Monitor
Track usage patterns and collect feedback from users. Rerun evaluations periodically to detect drift or regressions as workflows and models evolve. Usage analytics are not currently available through the Skills API. Implement application-level logging to track which Skills are included in requests.
6. 6
### Iterate or deprecate
Require the full evaluation suite to pass before promoting new versions. Update Skills when workflows change or evaluation scores decline. Deprecate Skills when evaluations consistently fail or the workflow is retired.
## Organizing Skills at scale
### Recall limits
As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude may fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.
Note that API requests support a maximum of 20 Skills for each request (see [Using Skills with the API](/docs/en/build-with-claude/skills-guide)). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.
### Start specific, consolidate later
Encourage teams to start with narrow, workflow-specific Skills rather than broad, multipurpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.
Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill's evaluations confirm equivalent performance to the individual Skills it replaces.
**Example progression:**
- Start: `formatting-sales-reports`, `querying-pipeline-data`, `updating-crm-records`
- Consolidate: `sales-operations` (when evals confirm equivalent performance)
### Naming and cataloging
Use consistent naming conventions across your organization. The [naming conventions](/docs/en/agents-and-tools/agent-skills/best-practices#naming-conventions) section in best practices provides formatting guidance.
Maintain an internal registry for each Skill with:
- **Purpose:** What workflow the Skill supports
- **Owner:** Team or individual responsible for maintenance
- **Version:** Current deployed version
- **Dependencies:** MCP servers, packages, or external services required
- **Evaluation status:** Last evaluation date and results
### Role-based bundles
Group Skills by organizational role to keep each user's active Skill set focused:
- **Sales team:** CRM operations, pipeline reporting, proposal generation
- **Engineering:** Code review, deployment workflows, incident response
- **Finance:** Report generation, data validation, audit preparation
Each role-based bundle should contain only the Skills relevant to that role's daily workflows.
## Distribution and version control
### Source control
Store Skill directories in Git for history tracking, code review through pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.
### API-based distribution
The Skills API provides workspace-scoped distribution. Skills uploaded through the API are available to all workspace members. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
### Versioning strategy
- **Production:** Pin Skills to specific versions. If you omit `version`, requests use the latest version, so a new version uploaded by anyone in the workspace immediately changes what production agents run. Run the full evaluation suite before promoting a new version. Treat every update as a new deployment requiring full security review.
- **Development and testing:** Use latest versions to validate changes before production promotion.
- **Rollback plan:** Maintain the previous version as a fallback. If a new version fails evaluations in production, revert to the last known-good version immediately.
- **Integrity verification:** Compute checksums of reviewed Skills and verify them at deployment time. Use signed commits in your Skill repository to ensure provenance.
### Cross-surface considerations
Custom Skills do not sync across surfaces. Skills uploaded to the API are not available on claude.ai or in Claude Code, and vice versa. Each surface requires separate uploads and management.
Maintain Skill source files in Git as the single source of truth. If your organization deploys Skills across multiple surfaces, implement your own synchronization process to keep them consistent. For full details, see [cross-surface availability](/docs/en/agents-and-tools/agent-skills/overview#cross-surface-availability).
## Next steps
[Agent Skills overview](/docs/en/agents-and-tools/agent-skills/overview)
Architecture and platform details
[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)
Authoring guidance for Skill creators
[Using Skills with the API](/docs/en/build-with-claude/skills-guide)
Upload and manage Skills programmatically
---
## Agents-Tools/agents-and-tools-agent-skills-enterprise-6168dda2cc.md
# Skills for enterprise
Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
---
This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see the [Skills overview](/docs/en/agents-and-tools/agent-skills/overview).
## Security review and vetting
Deploying Skills in an enterprise requires answering two distinct questions:
1. **Are Skills safe in general?** See the [security considerations](/docs/en/agents-and-tools/agent-skills/overview#security-considerations) section in the overview for platform-level security details.
2. **How do I vet a specific Skill?** Use the risk assessment and review checklist below.
### Risk tier assessment
Evaluate each Skill against these risk indicators before approving deployment:
| Risk indicator | What to look for | Concern level |
|---|---|---|
| Code execution | Scripts in the Skill directory (`*.py`, `*.sh`, `*.js`) | High: scripts run with full environment access |
| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude's behavior conditionally | High: can bypass security controls |
| MCP server references | Instructions referencing MCP tools (`ServerName:tool_name`) | High: extends access beyond the Skill itself |
| Network access patterns | URLs, API endpoints, `fetch`, `curl`, or `requests` calls | High: potential data exfiltration vector |
| Hardcoded credentials | API keys, tokens, or passwords in Skill files or scripts | High: secrets exposed in Git history and context window |
| File system access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: may access unintended data |
| Tool invocations | Instructions directing Claude to use bash, file operations, or other tools | Medium: review what operations are performed |
### Review checklist
Before deploying any Skill from a third party or internal contributor, complete these steps:
1. **Read all Skill directory content.** Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
2. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.
3. **Check for adversarial instructions.** Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.
4. **Check for external URL fetches or network calls.** Search scripts and instructions for network access patterns (`http`, `requests.get`, `urllib`, `curl`, `fetch`).
5. **Verify no hardcoded credentials.** Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.
6. **Identify tools and commands the Skill instructs Claude to invoke.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
7. **Confirm redirect destinations.** If the Skill references external URLs, verify they point to expected domains.
8. **Verify no data exfiltration patterns.** Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.
<Warning>
Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to execute arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.
</Warning>
## Evaluating Skills before deployment
Skills can degrade agent performance if they trigger incorrectly, conflict with other Skills, or provide poor instructions. Require evaluation before any production deployment.
### What to evaluate
Establish approval gates for these dimensions before deploying any Skill:
| Dimension | What it measures | Example failure |
|---|---|---|
| Triggering accuracy | Does the Skill activate for the right queries and stay inactive for unrelated ones? | Skill triggers on every spreadsheet mention, even when the user just wants to discuss data |
| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don't exist in its directory |
| Coexistence | Does adding this Skill degrade other Skills? | New Skill's description is too broad, stealing triggers from existing Skills |
| Instruction following | Does Claude follow the Skill's instructions accurately? | Claude skips validation steps or uses wrong libraries |
| Output quality | Does the Skill produce correct, useful results? | Generated reports have formatting errors or missing data |
### Evaluation requirements
Require Skill authors to submit evaluation suites with 3-5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), since Skill effectiveness varies by model.
For detailed guidance on building evaluations, see [evaluation and iteration](/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](/docs/en/test-and-evaluate/develop-tests).
### Using evaluations for lifecycle decisions
Evaluation results signal when to act:
- **Declining trigger accuracy:** Update the Skill's description or instructions
- **Coexistence conflicts:** Consolidate overlapping Skills or narrow descriptions
- **Consistently low output quality:** Rewrite instructions or add validation steps
- **Persistent failures across updates:** Deprecate the Skill
## Skill lifecycle management
<Steps>
<Step title="Plan">
Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
</Step>
<Step title="Create and review">
Ensure the Skill author follows [best practices](/docs/en/agents-and-tools/agent-skills/best-practices). Require a security review using the [review checklist](#review-checklist) above. Require an evaluation suite before approval. Establish separation of duties: Skill authors should not be their own reviewers.
</Step>
<Step title="Test">
Require evaluations in isolation (Skill alone) and alongside existing Skills (coexistence testing). Verify triggering accuracy, output quality, and absence of regressions across your active Skill set before approving for production.
</Step>
<Step title="Deploy">
Upload via the Skills API for workspace-wide access. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
</Step>
<Step title="Monitor">
Track usage patterns and collect feedback from users. Re-run evaluations periodically to detect drift or regressions as workflows and models evolve. Usage analytics are not currently available via the Skills API. Implement application-level logging to track which Skills are included in requests.
</Step>
<Step title="Iterate or deprecate">
Require the full evaluation suite to pass before promoting new versions. Update Skills when workflows change or evaluation scores decline. Deprecate Skills when evaluations consistently fail or the workflow is retired.
</Step>
</Steps>
## Organizing Skills at scale
### Recall limits
As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude may fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.
Note that API requests support a maximum of 8 Skills per request (see [Using Skills with the API](/docs/en/build-with-claude/skills-guide)). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.
### Start specific, consolidate later
Encourage teams to start with narrow, workflow-specific Skills rather than broad, multi-purpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.
<Tip>
Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill's evaluations confirm equivalent performance to the individual Skills it replaces.
</Tip>
**Example progression**:
- Start: `formatting-sales-reports`, `querying-pipeline-data`, `updating-crm-records`
- Consolidate: `sales-operations` (when evals confirm equivalent performance)
### Naming and cataloging
Use consistent naming conventions across your organization. The [naming conventions](/docs/en/agents-and-tools/agent-skills/best-practices#naming-conventions) section in best practices provides formatting guidance.
Maintain an internal registry for each Skill with:
- **Purpose**: What workflow the Skill supports
- **Owner**: Team or individual responsible for maintenance
- **Version**: Current deployed version
- **Dependencies**: MCP servers, packages, or external services required
- **Evaluation status**: Last evaluation date and results
### Role-based bundles
Group Skills by organizational role to keep each user's active Skill set focused:
- **Sales team**: CRM operations, pipeline reporting, proposal generation
- **Engineering**: Code review, deployment workflows, incident response
- **Finance**: Report generation, data validation, audit preparation
Each role-based bundle should contain only the Skills relevant to that role's daily workflows.
## Distribution and version control
### Source control
Store Skill directories in Git for history tracking, code review via pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.
### API-based distribution
The Skills API provides workspace-scoped distribution. Skills uploaded via the API are available to all workspace members. See [Using Skills with the API](/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
### Versioning strategy
- **Production**: Pin Skills to specific versions. Run the full evaluation suite before promoting a new version. Treat every update as a new deployment requiring full security review.
- **Development and testing**: Use latest versions to validate changes before production promotion.
- **Rollback plan**: Maintain the previous version as a fallback. If a new version fails evaluations in production, revert to the last known-good version immediately.
- **Integrity verification**: Compute checksums of reviewed Skills and verify them at deployment time. Use signed commits in your Skill repository to ensure provenance.
### Cross-surface considerations
<Warning>
Custom Skills do not sync across surfaces. Skills uploaded to the API are not available on claude.ai or in Claude Code, and vice versa. Each surface requires separate uploads and management.
</Warning>
Maintain Skill source files in Git as the single source of truth. If your organization deploys Skills across multiple surfaces, implement your own synchronization process to keep them consistent. For full details, see [cross-surface availability](/docs/en/agents-and-tools/agent-skills/overview#cross-surface-availability).
## Next steps
<CardGroup cols={2}>
<Card
title="Agent Skills overview"
icon="book-open"
href="/docs/en/agents-and-tools/agent-skills/overview"
>
Architecture and platform details
</Card>
<Card
title="Best practices"
icon="lightbulb"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Authoring guidance for Skill creators
</Card>
<Card
title="Using Skills with the API"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Upload and manage Skills programmatically
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-overview-5388df5d34.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Foverview)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Skills
# Agent Skills
Copy page
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
## Why use Skills
Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations.
**Key benefits:**
- **Specialize Claude:** Tailor capabilities for domain-specific tasks
- **Reduce repetition:** Create once, use automatically
- **Compose capabilities:** Combine Skills for complex, multistep tasks
For more on the architecture and real-world applications of Agent Skills, see the engineering blog post [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
## Using Skills
Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way: once a Skill is available in your environment, Claude uses it automatically when relevant to your request.
**Pre-built Agent Skills** are available on claude.ai, the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry). On Microsoft Foundry, Agent Skills require a [Hosted on Anthropic deployment](/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure). See [Available Skills](#available-skills) for the complete list.
**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them through the Claude API, or add them in claude.ai settings. On [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) and [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry), upload custom Skills through the Skills API.
**Get started:**
- For pre-built Agent Skills: See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using PowerPoint, Excel, Word, and PDF Skills in the API
- For custom Skills: See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) to learn how to create your own Skills
## How Skills work
Skills use Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
This filesystem-based architecture enables **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
Skills can contain three types of content, each loaded at a different time:
### Level 1: Metadata (always loaded)
The Skill's YAML frontmatter provides discovery information:
```python
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```
Claude loads this metadata at startup and includes it in the system prompt. The `description` is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it. This lightweight approach means you can install many Skills without context penalty: until a Skill is triggered, only its name and description occupy context.
### Level 2: Instructions (loaded when triggered)
The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
```` shiki
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For advanced form filling, see [FORMS.md](FORMS.md).
````
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.
### Level 3: Resources and code (loaded as needed)
Skills can bundle additional materials:
- `pdf-processing/`
- `SKILL.md` (main instructions)
- `FORMS.md` (form-filling guide)
- `REFERENCE.md` (detailed API reference)
- `scripts/`
- `fill_form.py` (utility script)
**Instructions:** Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
**Code:** Executable scripts (fill_form.py, validate.py) that Claude runs using bash, providing deterministic operations without loading their code into context
**Resources:** Reference materials such as database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
| Level | When loaded | Token cost | Content |
|---------------------------|-------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context |
Progressive disclosure ensures only relevant content occupies the context window at any given time.
### The Skills architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
**How Claude accesses Skill content:**
When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
**What this architecture enables:**
- **On-demand file access:** Claude reads only the files each task needs. A Skill can include dozens of reference files, but if your task only needs the sales schema, that's the one file Claude loads. The rest stay on the filesystem and cost zero tokens.
- **Efficient script execution:** When Claude runs `validate_form.py`, the script's code never loads into the context window. Only its output (such as "Validation passed" or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code on the fly.
- **No practical limit on bundled content:** Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.
### Example: Loading a PDF processing Skill
Here's how Claude loads and uses the custom `pdf-processing` Skill from the earlier examples (not the pre-built `pdf` Skill):
1. **Startup:** System prompt includes: `pdf-processing - Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
2. **User request:** "Extract the text from this PDF and summarize it"
3. **Claude invokes:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
4. **Claude determines:** Form filling is not needed, so FORMS.md is not read
5. **Claude executes:** Uses instructions from SKILL.md to complete the task
## Where Skills work
Skills are available across Claude's agent products:
Claude Platform on AWS and Microsoft Foundry inherit the same Skills behavior as the Claude API in all following sections, except where [Limitations and constraints](#limitations-and-constraints) says otherwise.
### Claude API
The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant `skill_id` in the `container` parameter along with the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool).
**Prerequisites:** Using Skills through the API requires the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool), whose container Skills run in.
Use pre-built Agent Skills by referencing their `skill_id` (`pptx`, `xlsx`, `docx`, or `pdf`), or create and upload your own through the Skills API (`/v1/skills` endpoints). Custom Skills are shared workspace-wide: all workspace members can access them.
Skills on the API run in a sandboxed container with no network access and no runtime package installation. See [Limitations and constraints](#limitations-and-constraints) for details.
To learn more, see [Using Agent Skills with the API](/docs/en/build-with-claude/skills-guide).
### Claude Code
[Claude Code](https://code.claude.com/docs/en/overview) supports custom Skills. The pre-built document Skills (PowerPoint, Excel, Word, PDF) are not available in Claude Code, though the open-source [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill) comes bundled with it. See the full list of [built-in commands and Skills](https://code.claude.com/docs/en/commands) that ship with Claude Code.
**Custom Skills:** Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).
To learn more, see [Use Skills in Claude Code](https://code.claude.com/docs/en/skills).
### claude.ai
[claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills.
**Pre-built Agent Skills:** These Skills are active when you create documents. Claude uses them with no setup required.
**Custom Skills:** Upload your own Skills as zip files through Settings \> Features. Available on Pro, Max, Team, and Enterprise plans with [code execution enabled](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude). Custom Skills are individual to each user. They are not shared organization-wide and cannot be centrally managed by admins.
To learn more about using Skills in claude.ai, see the following resources in the Claude Help Center:
- [What are Skills?](https://support.claude.com/en/articles/12512176-what-are-skills)
- [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
- [How to create custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
- [Teach Claude your way of working using Skills](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```python
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
```
**Required fields:** `name` and `description`
**Field requirements:**
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
The `description` must include both what the Skill does and when Claude should use it. For complete authoring guidance, see [Skill authoring best practices](/docs/en/agents-and-tools/agent-skills/best-practices).
## Security considerations
Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills give Claude new capabilities through instructions and code, which also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
**Key security considerations:**
- **Audit thoroughly:** Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns such as unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
- **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
- **Tool misuse:** Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
- **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems
- **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
For organization-scale governance, vetting, and deployment guidance, see [Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise). Claude Enterprise organizations can also turn on [Skill content scanning](/docs/en/agents-and-tools/agent-skills/enterprise#skill-content-scanning) for custom Skills uploaded in claude.ai and Claude Cowork. Scanning doesn't cover Skills uploaded through the Skills API or the Claude Console.
## Available Skills
### Pre-built Agent Skills
The following pre-built Agent Skills are available for immediate use:
- **PowerPoint (pptx):** Create presentations, edit slides, analyze presentation content
- **Excel (xlsx):** Create spreadsheets, analyze data, generate reports with charts
- **Word (docx):** Create documents, edit content, format text
- **PDF (pdf):** Generate formatted PDF documents and reports
These Skills are available on the Claude API, [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry), and claude.ai. See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using them in the API.
### Open-source Skills
Anthropic also publishes open-source Skills in the [skills repository](https://github.com/anthropics/skills):
- **[Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill):** Provides Claude with up-to-date API reference material, SDK documentation, and best practices for eight programming languages. Bundled with Claude Code and also available for installation from the skills repository.
### Custom Skills examples
For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
## Data retention
Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
For audit logging of Skills API operations, see [Audit logging](/docs/en/build-with-claude/skills-guide#audit-logging) in Using Agent Skills with the API.
## Limitations and constraints
Claude Platform on AWS and Microsoft Foundry follow the same limitations as the Claude API in the following subsections. In addition, on Microsoft Foundry, the [Skill version download endpoint](/docs/en/api/beta/skills/versions/download) (`GET /v1/skills/{skill_id}/versions/{version}/content`) is not supported.
### Cross-surface availability
**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
- Skills uploaded to claude.ai must be separately uploaded to the API
- Skills uploaded through the API are not available on claude.ai
- Claude Code Skills are filesystem-based and separate from both claude.ai and API
Manage and upload Skills separately for each surface where you want to use them.
### Sharing scope
Skills have different sharing models depending on where you use them:
- **claude.ai:** Individual user only. Each team member must upload separately.
- **Claude API:** Workspace-wide. All workspace members can access uploaded Skills.
- **Claude Code:** Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`). Can also be shared through Claude Code Plugins.
claude.ai does not support centralized admin management or org-wide distribution of custom Skills.
### Runtime environment constraints
The exact runtime environment available to your Skill depends on the product surface where you use it.
- **claude.ai:**
- **Varying network access:** Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
- **Claude API:**
- **No network access:** Skills cannot make external API calls or access the internet.
- **No runtime package installation:** Only pre-installed packages are available. You cannot install new packages during execution.
- **Pre-configured dependencies only:** Check the [Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation for the list of available packages.
- **Claude Code:**
- **Full network access:** Skills have the same network access as any other program on the user's computer.
- **Global package installation discouraged:** Skills should only install packages locally to avoid interfering with the user's computer.
Plan your Skills to work within these constraints.
## Next steps
[Get started with Agent Skills in the API](/docs/en/agents-and-tools/agent-skills/quickstart)
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
[Using Agent Skills with the API](/docs/en/build-with-claude/skills-guide)
Learn how to use Agent Skills to extend Claude's capabilities through the API.
[Use Skills in Claude Code](https://code.claude.com/docs/en/skills)
Create and manage custom Skills in Claude Code.
[Skill authoring best practices](/docs/en/agents-and-tools/agent-skills/best-practices)
Learn how to write effective Skills that Claude can discover and use successfully.
---
## Agents-Tools/agents-and-tools-agent-skills-overview-a6ba167cbe.md
# Agent Skills
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.
---
<Note>
This feature is **not** eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). Data is retained according to the feature's standard retention policy.
</Note>
## Why use Skills
Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
**Key benefits**:
- **Specialize Claude**: Tailor capabilities for domain-specific tasks
- **Reduce repetition**: Create once, use automatically
- **Compose capabilities**: Combine Skills to build complex workflows
<Note>
For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
</Note>
## Using Skills
Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way. Claude automatically uses them when relevant to your request.
**Pre-built Agent Skills** are available to all users on claude.ai and via the Claude API. See the [Available Skills](#available-skills) section below for the complete list.
**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them via the API, or add them in claude.ai settings.
<Note>
**Get started:**
- For pre-built Agent Skills: See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using PowerPoint, Excel, Word, and PDF skills in the API
- For custom Skills: See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) to learn how to create your own Skills
</Note>
## How Skills work
Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
This filesystem-based architecture enables **progressive disclosure**: Claude loads information in stages as needed, rather than consuming context upfront.
### Three types of Skill content, three levels of loading
Skills can contain three types of content, each loaded at different times:
### Level 1: Metadata (always loaded)
**Content type: Instructions**. The Skill's YAML frontmatter provides discovery information:
```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```
Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it.
### Level 2: Instructions (loaded when triggered)
**Content type: Instructions**. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
````markdown
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For advanced form filling, see [FORMS.md](FORMS.md).
````
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window.
### Level 3: Resources and code (loaded as needed)
**Content types: Instructions, code, and resources**. Skills can bundle additional materials:
```text
pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
└── fill_form.py (utility script)
```
**Instructions**: Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
**Code**: Executable scripts (fill_form.py, validate.py) that Claude runs via bash; scripts provide deterministic operations without consuming context
**Resources**: Reference materials like database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
| Level | When Loaded | Token Cost | Content |
|-------|------------|------------|---------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context |
Progressive disclosure ensures only relevant content occupies the context window at any given time.
### The Skills architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Think of it like this: Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
**How Claude accesses Skill content:**
When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (like FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them via bash and receives only the output (the script code itself never enters context).
**What this architecture enables:**
**On-demand file access**: Claude reads only the files needed for each specific task. A Skill can include dozens of reference files, but if your task only needs the sales schema, Claude loads just that one file. The rest remain on the filesystem consuming zero tokens.
**Efficient script execution**: When Claude runs `validate_form.py`, the script's code never loads into the context window. Only the script's output (like "Validation passed" or specific error messages) consumes tokens. This makes scripts far more efficient than having Claude generate equivalent code on the fly.
**No practical limit on bundled content**: Because files don't consume context until accessed, Skills can include comprehensive API documentation, large datasets, extensive examples, or any reference materials you need. There's no context penalty for bundled content that isn't used.
This filesystem-based model is what makes progressive disclosure work. Claude navigates your Skill like you'd reference specific sections of an onboarding guide, accessing exactly what each task requires.
### Example: Loading a PDF processing skill
Here's how Claude loads and uses a PDF processing skill:
1. **Startup**: System prompt includes: `PDF Processing - Extract text and tables from PDF files, fill forms, merge documents`
2. **User request**: "Extract the text from this PDF and summarize it"
3. **Claude invokes**: `bash: read pdf-skill/SKILL.md` → Instructions loaded into context
4. **Claude determines**: Form filling is not needed, so FORMS.md is not read
5. **Claude executes**: Uses instructions from SKILL.md to complete the task
The diagram shows:
1. Default state with system prompt and skill metadata pre-loaded
2. Claude triggers the skill by reading SKILL.md via bash
3. Claude optionally reads additional bundled files like FORMS.md as needed
4. Claude proceeds with the task
This dynamic loading ensures only relevant skill content occupies the context window.
## Where Skills work
Skills are available across Claude's agent products:
### Claude API
The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant `skill_id` in the `container` parameter along with the code execution tool.
**Prerequisites**: Using Skills via the API requires three beta headers:
- `code-execution-2025-08-25` - Skills run in the code execution container
- `skills-2025-10-02` - Enables Skills functionality
- `files-api-2025-04-14` - Required for uploading/downloading files to/from the container
Use pre-built Agent Skills by referencing their `skill_id` (for example, `pptx`, `xlsx`), or create and upload your own via the Skills API (`/v1/skills` endpoints). Custom Skills are shared organization-wide.
To learn more, see [Use Skills with the Claude API](/docs/en/build-with-claude/skills-guide).
### Claude Code
[Claude Code](../../02-Claude-Code-CLI/claude-code-overview-claude-code-docs-c23f3e7cbb.md) supports only Custom Skills.
**Custom Skills**: Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
Custom Skills in Claude Code are filesystem-based and don't require API uploads.
To learn more, see [Use Skills in Claude Code](../../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md).
### Claude.ai
[Claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills.
**Pre-built Agent Skills**: These Skills are already working behind the scenes when you create documents. Claude uses them without requiring any setup.
**Custom Skills**: Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled. Custom Skills are individual to each user; they are not shared organization-wide and cannot be centrally managed by admins.
To learn more about using Skills in Claude.ai, see the following resources in the Claude Help Center:
- [What are Skills?](../../02-Claude-Code-CLI/what-are-skills.md)
- [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
- [How to create custom Skills](../../02-Claude-Code-CLI/creating-custom-skills.md)
- [Teach Claude your way of working using Skills](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```yaml
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
```
**Required fields**: `name` and `description`
**Field requirements**:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
The `description` should include both what the Skill does and when Claude should use it. For complete authoring guidance, see the [best practices guide](/docs/en/agents-and-tools/agent-skills/best-practices).
## Security considerations
We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills provide Claude with new capabilities through instructions and code, and while this makes them powerful, it also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
<Warning>
If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
</Warning>
**Key security considerations**:
- **Audit thoroughly**: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns like unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
- **External sources are risky**: Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
- **Tool misuse**: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
- **Data exposure**: Skills with access to sensitive data could be designed to leak information to external systems
- **Treat like installing software**: Only use Skills from trusted sources. Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
## Available Skills
### Pre-built Agent Skills
The following pre-built Agent Skills are available for immediate use:
- **PowerPoint (pptx)**: Create presentations, edit slides, analyze presentation content
- **Excel (xlsx)**: Create spreadsheets, analyze data, generate reports with charts
- **Word (docx)**: Create documents, edit content, format text
- **PDF (pdf)**: Generate formatted PDF documents and reports
These Skills are available on the Claude API and claude.ai. See the [quickstart tutorial](/docs/en/agents-and-tools/agent-skills/quickstart) to start using them in the API.
### Open-source Skills
Anthropic also publishes open-source Skills in the [skills repository](https://github.com/anthropics/skills):
- **[Claude API](/docs/en/agents-and-tools/agent-skills/claude-api-skill)**: Provides Claude with up-to-date API reference material, SDK documentation, and best practices for 8 programming languages. Bundled with Claude Code and also available for installation from the skills repository.
### Custom Skills examples
For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
## Data retention
Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Limitations and constraints
Understanding these limitations helps you plan your Skills deployment effectively.
### Cross-surface availability
**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
- Skills uploaded to Claude.ai must be separately uploaded to the API
- Skills uploaded via the API are not available on Claude.ai
- Claude Code Skills are filesystem-based and separate from both Claude.ai and API
You'll need to manage and upload Skills separately for each surface where you want to use them.
### Sharing scope
Skills have different sharing models depending on where you use them:
- **Claude.ai**: Individual user only; each team member must upload separately
- **Claude API**: Workspace-wide; all workspace members can access uploaded Skills
- **Claude Code**: Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`); can also be shared via Claude Code Plugins
Claude.ai does not currently support centralized admin management or org-wide distribution of custom Skills.
### Runtime environment constraints
The exact runtime environment available to your skill depends on the product surface where you use it.
- **Claude.ai**:
- **Varying network access**: Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
- **Claude API**:
- **No network access**: Skills cannot make external API calls or access the internet
- **No runtime package installation**: Only pre-installed packages are available. You cannot install new packages during execution.
- **Pre-configured dependencies only**: Check the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool) for the list of available packages
- **Claude Code**:
- **Full network access**: Skills have the same network access as any other program on the user's computer
- **Global package installation discouraged**: Skills should only install packages locally in order to avoid interfering with the user's computer
Plan your Skills to work within these constraints.
## Next steps
<CardGroup cols={2}>
<Card
title="Get started with Agent Skills"
icon="graduation-cap"
href="/docs/en/agents-and-tools/agent-skills/quickstart"
>
Create your first Skill
</Card>
<Card
title="API Guide"
icon="code"
href="/docs/en/build-with-claude/skills-guide"
>
Use Skills with the Claude API
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Create and manage custom Skills in Claude Code
</Card>
<Card
title="Authoring best practices"
icon="lightbulb"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Write Skills that Claude can use effectively
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-quickstart-4b66ca78ee.md
# Get started with Agent Skills in the API
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
---
This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You'll learn how to enable Skills, make a simple request, and access the generated file.
## Prerequisites
- [Claude API key](/settings/keys)
- Python 3.7+ or curl installed
- Basic familiarity with making API requests
## Agent Skills overview
Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks like creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:
- **PowerPoint (pptx):** Create and edit presentations
- **Excel (xlsx):** Create and analyze spreadsheets
- **Word (docx):** Create and edit documents
- **PDF (pdf):** Generate PDF documents
<Note>
**Want to create custom Skills?** See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) for examples of building your own Skills with domain-specific expertise.
</Note>
## Step 1: List available Skills
First, check what Skills are available. Use the Skills API to list all Anthropic-managed Skills:
<CodeGroup defaultLanguage="CLI">
```bash cURL
curl "https://api.anthropic.com/v1/skills?source=anthropic" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02"
```
```bash CLI
ant beta:skills list --source anthropic
```
```python Python
import anthropic
client = anthropic.Anthropic()
# List Anthropic-managed Skills
skills = client.beta.skills.list(source="anthropic")
for skill in skills.data:
print(f"{skill.id}: {skill.display_title}")
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// List Anthropic-managed Skills
const skills = await client.beta.skills.list({
source: "anthropic"
});
for (const skill of skills.data) {
console.log(`${skill.id}: ${skill.display_title}`);
}
```
</CodeGroup>
You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`.
This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to know what Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.
## Step 2: Create a presentation
Now use the PowerPoint Skill to create a presentation about renewable energy. Specify Skills using the `container` parameter in the Messages API:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pptx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 \
--transform content <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy with 5 slides
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
import anthropic
client = anthropic.Anthropic()
# Create a message with the PowerPoint Skill
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.content)
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Create a message with the PowerPoint Skill
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pptx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a presentation about renewable energy with 5 slides"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
console.log(response.content);
```
</CodeGroup>
Let's break down what each part does:
- **`container.skills`:** Specifies which Skills Claude can use
- **`type: "anthropic"`:** Indicates this is an Anthropic-managed Skill
- **`skill_id: "pptx"`:** The PowerPoint Skill identifier
- **`version: "latest"`:** The Skill version set to the most recently published
- **`tools`:** Enables code execution (required for Skills)
- **Beta headers:** `code-execution-2025-08-25` and `skills-2025-10-02`
When you make this request, Claude automatically matches your task to the relevant Skill. Since you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude executes the Skill's code to create your presentation.
## Step 3: Download the created file
The presentation was created in the code execution container and saved as a file. The response includes a file reference with a file ID. Extract the file ID and download it using the Files API:
<CodeGroup>
```bash cURL nocheck
# Extract file_id from response (using jq)
FILE_ID=$(echo "$RESPONSE" | jq -r '.content[] | select(.type=="tool_use" and .name=="code_execution") | .content[] | select(.file_id) | .file_id')
# Download the file
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: files-api-2025-04-14" \
--output renewable_energy.pptx
echo "Presentation saved to renewable_energy.pptx"
```
```bash CLI nocheck
# Extract file_id with --transform on the messages create call
FILE_ID=$(ant beta:messages create \
--beta code-execution-2025-08-25 --beta skills-2025-10-02 \
--transform 'content.#.content.content.#.file_id|@flatten|0' \
--format yaml <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pptx
version: latest
messages:
- role: user
content: Create a presentation about renewable energy with 5 slides
tools:
- type: code_execution_20250825
name: code_execution
YAML
)
# Download the file
ant beta:files download \
--file-id "$FILE_ID" \
--output renewable_energy.pptx
printf 'Presentation saved to renewable_energy.pptx\n'
```
```python Python nocheck
from typing import Any
response: Any = None
# Extract file ID from response
file_id = None
for block in response.content:
if block.type == "tool_use" and block.name == "code_execution":
# File ID is in the tool result
for result_block in block.content:
if hasattr(result_block, "file_id"):
file_id = result_block.file_id
break
if file_id:
# Download the file
file_content = client.beta.files.download(file_id=file_id)
# Save to disk
with open("renewable_energy.pptx", "wb") as f:
file_content.write_to_file(f.name)
print(f"Presentation saved to renewable_energy.pptx")
```
```typescript TypeScript nocheck
// Extract file ID from response
let fileId: string | null = null;
for (const block of response.content) {
if (block.type === "tool_use" && block.name === "code_execution") {
// File ID is in the tool result
for (const resultBlock of block.content) {
if ("file_id" in resultBlock) {
fileId = resultBlock.file_id;
break;
}
}
}
}
if (fileId) {
// Download the file
const fileContent = await client.beta.files.download(fileId);
// Save to disk
const fs = require("fs/promises");
await fs.writeFile("renewable_energy.pptx", Buffer.from(await fileContent.arrayBuffer()));
console.log("Presentation saved to renewable_energy.pptx");
}
```
</CodeGroup>
<Note>
For complete details on working with generated files, see the [code execution tool documentation](/docs/en/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files).
</Note>
## Try more examples
Now that you've created your first document with Skills, try these variations:
### Create a spreadsheet
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "xlsx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: xlsx
version: latest
messages:
- role: user
content: Create a quarterly sales tracking spreadsheet with sample data
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "xlsx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Create a quarterly sales tracking spreadsheet with sample data"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
### Create a Word document
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "docx",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI nocheck
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: docx
version: latest
messages:
- role: user
content: Write a 2-page report on the benefits of renewable energy
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "docx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "docx",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Write a 2-page report on the benefits of renewable energy"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
### Generate a PDF
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 4096,
"container": {
"skills": [
{
"type": "anthropic",
"skill_id": "pdf",
"version": "latest"
}
]
},
"messages": [{
"role": "user",
"content": "Generate a PDF invoice template"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'
```
```bash CLI
ant beta:messages create \
--beta code-execution-2025-08-25 \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-7
max_tokens: 4096
container:
skills:
- type: anthropic
skill_id: pdf
version: latest
messages:
- role: user
content: Generate a PDF invoice template
tools:
- type: code_execution_20250825
name: code_execution
YAML
```
```python Python
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]
},
messages=[{"role": "user", "content": "Generate a PDF invoice template"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
```
```typescript TypeScript
const response = await client.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 4096,
betas: ["code-execution-2025-08-25", "skills-2025-10-02"],
container: {
skills: [
{
type: "anthropic",
skill_id: "pdf",
version: "latest"
}
]
},
messages: [
{
role: "user",
content: "Generate a PDF invoice template"
}
],
tools: [
{
type: "code_execution_20250825",
name: "code_execution"
}
]
});
```
</CodeGroup>
## Next steps
Now that you've used pre-built Agent Skills, you can:
<CardGroup cols={2}>
<Card
title="API Guide"
icon="book"
href="/docs/en/build-with-claude/skills-guide"
>
Use Skills with the Claude API
</Card>
<Card
title="Create Custom Skills"
icon="code"
href="/docs/en/api/skills/create-skill"
>
Upload your own Skills for specialized tasks
</Card>
<Card
title="Authoring Guide"
icon="edit"
href="/docs/en/agents-and-tools/agent-skills/best-practices"
>
Learn best practices for writing effective Skills
</Card>
<Card
title="Use Skills in Claude Code"
icon="terminal"
href="https://code.claude.com/docs/en/skills"
>
Learn about Skills in Claude Code
</Card>
<Card
title="Agent Skills Cookbook"
icon="book"
href="https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction"
>
Explore example Skills and implementation patterns
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-agent-skills-quickstart-9d70739541.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fquickstart)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Skills
# Get started with Agent Skills in the API
Copy page
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
Copy page
This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You'll learn how to enable Skills, make a request, and access the generated file.
## Prerequisites
- A [Claude API key](/settings/keys) or a logged-in [ant CLI](/docs/en/cli-sdks-libraries/cli/authentication)
- A [client SDK](/docs/en/cli-sdks-libraries/overview) for your language, or `curl` and `jq`
- Basic familiarity with making API requests
## Agent Skills overview
Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks such as creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:
- **PowerPoint (pptx):** Create and edit presentations
- **Excel (xlsx):** Create and analyze spreadsheets
- **Word (docx):** Create and edit documents
- **PDF (pdf):** Generate PDF documents
To create custom Skills, see the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) for examples of building your own Skills with domain-specific expertise.
## Step 1: List available Skills
First, check what Skills are available. Use the Skills API to list all Anthropic-managed Skills. Each language tab is an excerpt from one continuous script, with any imports and client setup at the top:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# List Anthropic-managed Skills
skills = client.skills.list(source="anthropic")
for skill in skills.data:
print(f"{skill.id}: {skill.display_name}")
```
You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`.
This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to determine which Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.
## Step 2: Create a presentation
Use the PowerPoint Skill to create a presentation about renewable energy. Specify Skills using the `container` parameter in the Messages API:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# Create a message with the PowerPoint Skill
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
print(f"stop_reason={response.stop_reason}, blocks={len(response.content)}")
```
The request includes the following parts:
- **`model`:** A [model that supports the code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool#compatibility)
- **`container.skills`:** Specifies which Skills Claude can use
- **`type: "anthropic"`:** Indicates this is an Anthropic-managed Skill
- **`skill_id: "pptx"`:** The PowerPoint Skill identifier
- **`version: "latest"`:** The Skill version set to the most recently published
- **`tools`:** Enables code execution (required for Skills)
The examples use the `code_execution_20260521` tool version, and the Step 3 code parses the result types that current tool versions return. Skills also work with older [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool) versions such as `code_execution_20250825`: any current code execution tool version satisfies the Skills requirement. If you use a different version, use the tool `type` listed on the code execution tool page.
When you make this request, Claude automatically matches your task to the relevant Skill. Because you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude runs the Skill's code to create your presentation.
## Step 3: Download the created file
The presentation was created in the code execution container and saved as a file. The Step 2 `response` includes a file reference with a file ID. Extract the file ID and download the file with the Files API. The example saves it to your system temp directory:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# Extract the file ID. The code execution tool runs the Skill's code through
# its Bash sub-tool, and generated files appear as bash_code_execution_output
# items inside the bash_code_execution_tool_result block.
file_id = None
for block in response.content:
if block.type == "bash_code_execution_tool_result":
if block.content.type == "bash_code_execution_result":
for output in block.content.content:
file_id = output.file_id
if file_id:
# Download the file and save it
output_path = Path(tempfile.gettempdir()) / "renewable_energy.pptx"
file_content = client.files.download(file_id=file_id)
file_content.write_to_file(output_path)
print(f"Presentation saved to {output_path}")
```
For complete details on working with generated files, see [Retrieve generated files](/docs/en/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) in the code execution tool documentation.
## Try more examples
Try these variations:
### Create a spreadsheet
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
### Create a Word document
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "docx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
### Generate a PDF
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Generate a PDF invoice template",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
## Next steps
[Skill authoring best practices](/docs/en/agents-and-tools/agent-skills/best-practices)
Learn how to write effective Skills that Claude can discover and use successfully.
[Using Agent Skills with the API](/docs/en/build-with-claude/skills-guide)
Learn how to use Agent Skills to extend Claude's capabilities through the API.
[Create custom Skills](/docs/en/api/skills/create)
Upload your own Skills for specialized tasks.
[Use Skills in Claude Code](https://code.claude.com/docs/en/skills)
Learn about Skills in Claude Code.
[Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction)
Explore example Skills and implementation patterns.
---
## Agents-Tools/agents-and-tools-mcp-connector-2b3ff19436.md
# MCP connector
---
Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
<Note>
**Current version**: This feature requires the beta header: `"anthropic-beta": "mcp-client-2025-11-20"`
The previous version (`mcp-client-2025-04-04`) is deprecated. See the [deprecated version documentation](#deprecated-version-mcp-client-2025-04-04) below.
</Note>
<Note>
This feature is **not** eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). Data is retained according to the feature's standard retention policy.
</Note>
## Key features
- **Direct API integration**: Connect to MCP servers without implementing an MCP client
- **Tool calling support**: Access MCP tools through the Messages API
- **Flexible tool configuration**: Enable all tools, allowlist specific tools, or denylist unwanted tools
- **Per-tool configuration**: Configure individual tools with custom settings
- **OAuth authentication**: Support for OAuth Bearer tokens for authenticated servers
- **Multiple servers**: Connect to multiple MCP servers in a single request
## Limitations
- Of the feature set of the [MCP specification](https://modelcontextprotocol.io/introduction#explore-mcp), only [tool calls](https://modelcontextprotocol.io/docs/concepts/tools) are currently supported.
- The server must be publicly exposed through HTTP (supports both Streamable HTTP and SSE transports). Local STDIO servers cannot be connected directly.
- The MCP connector is currently not supported on Amazon Bedrock and Google Vertex.
## Using the MCP connector in the Messages API
The MCP connector uses two components:
1. **MCP Server Definition** (`mcp_servers` array): Defines server connection details (URL, authentication)
2. **MCP Toolset** (`tools` array): Configures which tools to enable and how to configure them
### Basic example
This example enables all tools from an MCP server with default configuration:
<CodeGroup>
```bash cURL nocheck
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [{"role": "user", "content": "What tools do you have available?"}],
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp"
}
]
}'
```
```bash CLI nocheck
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-4-7
max_tokens: 1000
messages:
- role: user
content: What tools do you have available?
mcp_servers:
- type: url
url: https://example-server.modelcontextprotocol.io/sse
name: example-mcp
authorization_token: YOUR_TOKEN
tools:
- type: mcp_toolset
mcp_server_name: example-mcp
YAML
```
```python Python nocheck hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=1000,
messages=[{"role": "user", "content": "What tools do you have available?"}],
mcp_servers=[
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1000,
messages: [
{
role: "user",
content: "What tools do you have available?"
}
],
mcp_servers: [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
],
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp"
}
],
betas: ["mcp-client-2025-11-20"]
});
console.log(response);
```
```csharp C# nocheck hidelines={1..6}
using Anthropic;
using Anthropic.Models.Beta.Messages;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_7,
MaxTokens = 1000,
Messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List<BetaRequestMcpServerUrlDefinition>
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List<BetaToolUnion>
{
new BetaMcpToolset("example-mcp")
},
Betas = new List<string> { "mcp-client-2025-11-20" }
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go nocheck hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus4_7,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```java Java nocheck hidelines={1..2,4,6..9,-2..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
public class Main {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-4-7")
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta("mcp-client-2025-11-20")
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);
}
}
```
```php PHP nocheck hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-4-7',
mcpServers: [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
],
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
],
],
betas: ['mcp-client-2025-11-20'],
);
echo $message;
```
```ruby Ruby nocheck hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-4-7",
max_tokens: 1000,
messages: [
{ role: "user", content: "What tools do you have available?" }
],
mcp_servers: [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
],
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp"
}
],
betas: ["mcp-client-2025-11-20"]
)
puts response
```
</CodeGroup>
## MCP server configuration
Each MCP server in the `mcp_servers` array defines the connection details:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Field descriptions
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Currently only "url" is supported |
| `url` | string | Yes | The URL of the MCP server. Must start with https:// |
| `name` | string | Yes | A unique identifier for this MCP server. Must be referenced by exactly one MCPToolset in the `tools` array. |
| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [MCP specification](../../06-MCP-Tools/Spec/spec-2025-11-25-authorization-model-context-protocol.md). |
## MCP toolset configuration
The MCPToolset lives in the `tools` array and configures which tools from the MCP server are enabled and how they should be configured.
### Basic structure
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}
```
### Field descriptions
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Must be "mcp_toolset" |
| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array |
| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` will override these defaults. |
| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
| `cache_control` | object | No | Cache breakpoint configuration for this toolset |
### Tool configuration options
Each tool (whether configured in `default_config` or in `configs`) supports the following fields:
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `enabled` | boolean | `true` | Whether this tool is enabled |
| `defer_loading` | boolean | `false` | If true, tool description is not sent to the model initially. Used with [Tool Search Tool](/docs/en/agents-and-tools/tool-use/tool-search-tool). |
For the full directory of Anthropic-provided tools and optional properties like `defer_loading`, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). For searching across large tool sets, see [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool).
### Configuration merging
Configuration values merge with this precedence (highest to lowest):
1. Tool-specific settings in `configs`
2. Set-level `default_config`
3. System defaults
Example:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Results in:
- `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default_config)
- All other tools: `enabled: true` (system default), `defer_loading: true` (from default_config)
## Common configuration patterns
### Enable all tools with default configuration
The simplest pattern - enable all tools from a server:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist - Enable only specific tools
Set `enabled: false` as the default, then explicitly enable specific tools:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist - Disable specific tools
Enable all tools by default, then explicitly disable unwanted tools:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Mixed - Allowlist with per-tool configuration
Combine allowlisting with custom configuration for each tool:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}
```
In this example:
- `search_events` is enabled with `defer_loading: false`
- `list_events` is enabled with `defer_loading: true` (inherited from default_config)
- All other tools are disabled
## Validation rules
The API enforces these validation rules:
- **Server must exist**: The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
- **Server must be used**: Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
- **Unique toolset per server**: Each MCP server can only be referenced by one MCPToolset
- **Unknown tool names**: If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)
## Response content types
When Claude uses MCP tools, the response will include two new content block types:
### MCP Tool Use Block
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP Tool Result Block
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Multiple MCP servers
You can connect to multiple MCP servers by including multiple server definitions in `mcp_servers` and a corresponding MCPToolset for each in the `tools` array:
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
}
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example1.com/sse",
"name": "mcp-server-1",
"authorization_token": "TOKEN1"
},
{
"type": "url",
"url": "https://mcp.example2.com/sse",
"name": "mcp-server-2",
"authorization_token": "TOKEN2"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-1"
},
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-2",
"default_config": {
"defer_loading": true
}
}
]
}
```
## Authentication
For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition.
API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, as well as refreshing the token as needed.
### Obtaining an access token for testing
The MCP inspector can guide you through the process of obtaining an access token for testing purposes.
1. Run the inspector with the following command. You need Node.js installed on your machine.
```bash
npx @modelcontextprotocol/inspector
```
2. In the sidebar on the left, for "Transport type", select either "SSE" or "Streamable HTTP".
3. Enter the URL of the MCP server.
4. In the right area, click on the "Open Auth Settings" button after "Need to configure authentication?".
5. Click "Quick OAuth Flow" and authorize on the OAuth screen.
6. Follow the steps in the "OAuth Flow Progress" section of the inspector and click "Continue" until you reach "Authentication complete".
7. Copy the `access_token` value.
8. Paste it into the `authorization_token` field in your MCP server configuration.
### Using the access token
Once you've obtained an access token using either OAuth flow above, you can use it in your MCP server configuration:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
For detailed explanations of the OAuth flow, refer to the [Authorization section](../../06-MCP-Tools/Spec/spec-2025-11-25-authorization-model-context-protocol.md) in the MCP specification.
## Client-side MCP helpers (TypeScript)
If you manage your own MCP client connection (for example, with local stdio servers, MCP prompts, or MCP resources), the TypeScript SDK provides helper functions that convert between MCP types and Claude API types. This eliminates manual conversion code when using the [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) alongside the Anthropic SDK.
<Note>
These helpers are currently available in the TypeScript SDK only.
</Note>
<Note>
Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible via URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK.
</Note>
### Installation
Install both the Anthropic SDK and the MCP SDK:
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
### Available helpers
Import the helpers from the beta namespace:
```typescript nocheck
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
| Helper | Description |
|--------|-------------|
| `mcpTools(tools, mcpClient)` | Converts MCP tools to Claude API tools for use with `client.beta.messages.toolRunner()` |
| `mcpMessages(messages)` | Converts MCP prompt messages to Claude API message format |
| `mcpResourceToContent(resource)` | Converts an MCP resource to a Claude API content block |
| `mcpResourceToFile(resource)` | Converts an MCP resource to a file object for upload |
### Use MCP tools
Convert MCP tools for use with the SDK's [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:
```typescript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const anthropic = new Anthropic();
// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClient)
});
```
### Use MCP prompts
Convert MCP prompt messages into Claude API message format:
```typescript nocheck
import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: mcpMessages(messages)
});
```
### Use MCP resources
Convert MCP resources into content blocks to include in messages, or into file objects for upload:
```typescript nocheck
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
model: "claude-opus-4-7",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });
```
### Error handling
The conversion functions throw `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API. This can happen with unsupported content types, MIME types, or non-HTTP resource links.
## Data retention
The MCP Connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/build-with-claude/api-and-data-retention).
## Migration guide
If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
### Key changes
1. **New beta header**: Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
2. **Tool configuration moved**: Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
3. **More flexible configuration**: New pattern supports allowlisting, denylisting, and per-tool configuration
### Migration steps
**Before (deprecated):**
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}
```
**After (current):**
```json
{
"model": "claude-opus-4-7",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": false
},
"configs": {
"tool1": {
"enabled": true
},
"tool2": {
"enabled": true
}
}
}
]
}
```
### Common migration patterns
| Old pattern | New pattern |
|-------------|-------------|
| No `tool_configuration` (all tools enabled) | MCPToolset with no `default_config` or `configs` |
| `tool_configuration.enabled: false` | MCPToolset with `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset with `default_config.enabled: false` and specific tools enabled in `configs` |
## Deprecated version: mcp-client-2025-04-04
<Note type="warning">
This version is deprecated. Migrate to `mcp-client-2025-11-20` using the [migration guide](#migration-guide) above.
</Note>
The previous version of the MCP connector included tool configuration directly in the MCP server definition:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}
```
### Deprecated field descriptions
| Property | Type | Description |
|----------|------|-------------|
| `tool_configuration` | object | **Deprecated**: Use MCPToolset in the `tools` array instead |
| `tool_configuration.enabled` | boolean | **Deprecated**: Use `default_config.enabled` in MCPToolset |
| `tool_configuration.allowed_tools` | array | **Deprecated**: Use allowlist pattern with `configs` in MCPToolset |
---
## Agents-Tools/agents-and-tools-mcp-connector-83e0e00209.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-connector)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP
# MCP connector
Copy page
Connect to remote MCP servers directly from the Messages API without an MCP client, and allowlist, denylist, or configure individual tools.
Copy page
MCP connector
[Beta](/docs/en/build-with-claude/overview#feature-availability)
[Beta header](/docs/en/api/beta-headers)
mcp-client-2025-11-20
[ZDR](/docs/en/manage-claude/api-and-data-retention)
Not eligible
Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
The previous version of this feature (`mcp-client-2025-04-04`) is deprecated. See [Deprecated version: mcp-client-2025-04-04](#deprecated-version-mcp-client-2025-04-04).
## Key features
- **Direct API integration:** Connect to MCP servers without implementing an MCP client
- **Tool calling support:** Access MCP tools through the Messages API
- **Flexible tool configuration:** Enable all tools, allowlist specific tools, or denylist unwanted tools
- **Per-tool configuration:** Configure individual tools with custom settings
- **OAuth authentication:** Support for OAuth Bearer tokens for authenticated servers
- **Multiple servers:** Connect to multiple MCP servers in a single request
## When Claude uses MCP tools
Once an MCP server is connected, Claude calls its tools when the user's request maps to a tool's described capability, either explicitly ("search Jira for open bugs") or implicitly ("what's blocking the release?" with a Jira server attached).
Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking "how do Notion databases work?" with a Notion server attached is answered directly; asking "what's in my Projects database?" triggers the tool.
You can steer how readily Claude calls MCP tools through your system prompt. See [When Claude uses tools](/docs/en/agents-and-tools/tool-use/overview#when-claude-uses-tools) for general guidance and example phrasings.
## Limitations
- Of the feature set of the [MCP specification](https://modelcontextprotocol.io/introduction#explore-mcp), only [tool calls](https://modelcontextprotocol.io/docs/concepts/tools) are currently supported.
- The server must be publicly exposed through HTTP (supports both Streamable HTTP and SSE transports). Local STDIO servers cannot be connected directly.
## Using the MCP connector in the Messages API
The MCP connector uses two components:
1. **MCP server definition** (`mcp_servers` array): Defines server connection details (URL, authentication)
2. **MCP toolset** (`tools` array): Configures which tools to enable and how to configure them
### Basic example
This example enables all tools from an MCP server with default configuration:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1000,
messages=[{"role": "user", "content": "What tools do you have available?"}],
mcp_servers=[
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
## MCP server configuration
Each MCP server in the `mcp_servers` array defines the connection details:
```python
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Field descriptions
| Property | Type | Required | Description |
|-----------------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | string | Yes | Currently only "url" is supported. |
| `url` | string | Yes | The URL of the MCP server. Must start with https://. |
| `name` | string | Yes | A unique identifier for this MCP server. Must be referenced by exactly one MCPToolset in the `tools` array. |
| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [Authentication](#authentication) for how to obtain one, or the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for protocol details. |
## MCP toolset configuration
The MCPToolset lives in the `tools` array and configures which tools from the MCP server are enabled and how they should be configured.
### Basic structure
```python
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}
```
### Field descriptions
| Property | Type | Required | Description |
|-------------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------|
| `type` | string | Yes | Must be "mcp_toolset". |
| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array. |
| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` override these defaults. |
| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
| `cache_control` | object | No | [Prompt caching](/docs/en/build-with-claude/prompt-caching) cache breakpoint configuration for this toolset. |
With the `mcp-client-2026-09-15` beta header, an MCPToolset also accepts `tools`, a pinned copy of the server's tool list. See [Pin an MCP server's tool list](#pin-mcp-tool-list).
### Tool configuration options
Each tool (whether configured in `default_config` or in `configs`) supports the following fields:
| Property | Type | Default | Description |
|-----------------|---------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `enabled` | boolean | `true` | Whether this tool is enabled. |
| `defer_loading` | boolean | `false` | If true, tool description is not sent to the model initially. Used with [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool). |
For the full directory of Anthropic-provided tools and optional properties such as `defer_loading`, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference). To search across large tool sets, see [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool).
### Configuration merging
Configuration values merge with this precedence (highest to lowest):
1. Tool-specific settings in `configs`
2. Set-level `default_config`
3. System defaults
Example:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Results in:
- `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default_config)
- All other tools: `enabled: true` (system default), `defer_loading: true` (from default_config)
## Common configuration patterns
### Enable all tools with default configuration
The simplest pattern: enable all tools from a server:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist: enable only specific tools
Set `enabled: false` as the default, then explicitly enable specific tools:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist: disable specific tools
Enable all tools by default, then explicitly disable unwanted tools. Denylisting write or destructive tools is recommended when building read-only assistants, or when you want a human confirmation step before state changes:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Mixed: allowlist with per-tool configuration
Combine allowlisting with custom configuration for each tool:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}
```
In this example:
- `search_events` is enabled with `defer_loading: false`
- `list_events` is enabled with `defer_loading: true` (inherited from default_config)
- All other tools are disabled
## Validation rules
The API enforces these validation rules:
- **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
- **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
- **Unique toolset per server:** Each MCP server can only be referenced by one MCPToolset
- **Unknown tool names:** If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)
## Response content types
When Claude uses MCP tools, the response includes two new content block types:
### MCP tool use block
```python
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP tool result block
```python
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Pin an MCP server's tool list (beta)
An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn't change what Claude sees partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It's available on the Claude API.
When the API asks an MCP server for its tools while producing a response, the response starts with an `mcp_tool_listing` block for that server, one block for each server it asked:
```python
{
"type": "mcp_tool_listing",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
If your code reads `content[0]`, skip these blocks. Send the assistant message back unchanged, `mcp_tool_listing` blocks included, and keep sending `mcp-client-2026-09-15` on every request that carries one. Later requests then use the recorded list for that server instead of asking it again.
To pin a list yourself, copy a block's `tools` into the `tools` field of that server's MCPToolset. The API then doesn't ask the server for its tools, and the toolset's tools are exactly those entries, with `default_config` and `configs` applied:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Each entry in `tools` holds the tool's `name` as the server lists it (without the server name), its `description`, and its `input_schema`.
The following example sends one request with an unpinned toolset, copies the returned list into the toolset's `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn't ask the server:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
from anthropic.types.beta import (
BetaMessageParam,
BetaRequestMCPServerURLDefinitionParam,
)
client = anthropic.Anthropic()
mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
},
]
messages: list[BetaMessageParam] = [
{"role": "user", "content": "What tools do you have available?"},
]
# First request: the toolset isn't pinned, so the API asks the server for
# its tools and the response starts with an mcp_tool_listing block.
first = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
messages=messages,
)
listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])
# Pin the list: copy the block's tools into the toolset. The API uses
# exactly these entries and doesn't ask the server again.
second = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": tool.name,
"description": tool.description,
"input_schema": tool.input_schema,
}
for tool in listing.tools
],
},
],
messages=messages,
)
# With a pinned toolset, the response has no mcp_tool_listing block.
print([block.type for block in second.content])
```
With the `inline-tools-2026-09-15` beta header as well, you can add an MCP server partway through a conversation. See [Add an MCP server mid-conversation](/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## Multiple MCP servers
You can connect to multiple MCP servers by including multiple server definitions in `mcp_servers` and a corresponding MCPToolset for each in the `tools` array:
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
}
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example1.com/sse",
"name": "mcp-server-1",
"authorization_token": "TOKEN1"
},
{
"type": "url",
"url": "https://mcp.example2.com/sse",
"name": "mcp-server-2",
"authorization_token": "TOKEN2"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-1"
},
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-2",
"default_config": {
"defer_loading": true
}
}
]
}
```
With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](#tool-configuration-options) with the [Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool) so only relevant tools are surfaced per query.
## Authentication
For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.
### Obtaining an access token for testing
The MCP inspector can guide you through the process of obtaining an access token for testing purposes.
1. Run the inspector with the following command. You need Node.js installed on your machine.
``` shiki
npx @modelcontextprotocol/inspector
```
2. In the sidebar on the left, for **Transport type**, select either **SSE** or **Streamable HTTP**.
3. Enter the URL of the MCP server.
4. In the right area, click **Open Auth Settings** after **Need to configure authentication?**.
5. Click **Quick OAuth Flow** and authorize on the OAuth screen.
6. Follow the steps in the **OAuth Flow Progress** section of the inspector and click **Continue** until you reach **Authentication complete**.
7. Copy the `access_token` value.
8. Paste it into the `authorization_token` field in your MCP server configuration.
### Using the access token
Once you've obtained an access token using either of the preceding OAuth flows, you can use it in your MCP server configuration:
```python
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
For detailed explanations of the OAuth flow, refer to the [Authorization section](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) in the MCP specification.
## Client-side MCP helpers
If you manage your own MCP client connection (for example, with local stdio servers, MCP prompts, or MCP resources), the SDKs provide helper functions that convert between MCP types and Claude API types. This eliminates manual conversion code when using an MCP SDK for your language (for example, the [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)) alongside the Anthropic SDK.
Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible by URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK.
### Installation
Install both the Anthropic SDK and the MCP SDK:
Python
TypeScript
C#
Go
Java
PHP
Ruby
The MCP helpers are included in the `mcp` extra, which requires Python 3.10 or later:
```python
pip install "anthropic[mcp]"
```
### Available helpers
Import the helpers for your language:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
Helper names and exact signatures follow each language's conventions; this table shows the TypeScript forms:
| Helper | Description |
|----------------------------------|-----------------------------------------------------------------------------------------|
| `mcpTools(tools, mcpClient)` | Converts MCP tools to Claude API tools for use with `client.beta.messages.toolRunner()` |
| `mcpMessages(messages)` | Converts MCP prompt messages to Claude API message format |
| `mcpResourceToContent(resource)` | Converts an MCP resource to a Claude API content block |
| `mcpResourceToFile(resource)` | Converts an MCP resource to a file object for upload |
### Use MCP tools
Convert MCP tools for use with the SDK's [tool runner](/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
client = AsyncAnthropic()
async def main() -> None:
# Connect to an MCP server
server_params = StdioServerParameters(command="mcp-server")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
# List tools and convert them for the Claude API
tools_result = await mcp_client.list_tools()
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "What tools do you have available?"},
],
tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
)
final_message = await runner.until_done()
print(final_message)
asyncio.run(main())
```
### Use MCP prompts
Convert MCP prompt messages into Claude API message format:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[mcp_message(message) for message in prompt.messages],
)
print(response)
```
### Use MCP resources
Convert MCP resources into content blocks to include in messages, or into file objects for upload:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}
],
)
print(response)
# As a file upload
file_resource = await mcp_client.read_resource(
uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
### Error handling
The conversion functions fail with `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).
## Batch requests
You can include `mcp_servers` in [Message Batches API](/docs/en/build-with-claude/batch-processing) requests. MCP tool calls through the Batches API are priced the same as those in regular Messages API requests.
## Data retention
The MCP connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
## Migration guide
If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
### Key changes
1. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
2. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
3. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration
### Migration steps
**Before (deprecated):**
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}
```
**After (current):**
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": false
},
"configs": {
"tool1": {
"enabled": true
},
"tool2": {
"enabled": true
}
}
}
]
}
```
### Common migration patterns
| Old pattern | New pattern |
|---------------------------------------------|-----------------------------------------------------------------------------------------|
| No `tool_configuration` (all tools enabled) | MCPToolset with no `default_config` or `configs` |
| `tool_configuration.enabled: false` | MCPToolset with `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset with `default_config.enabled: false` and specific tools enabled in `configs` |
## Deprecated version: mcp-client-2025-04-04
This version is deprecated. Migrate to `mcp-client-2025-11-20` using the preceding [migration guide](#migration-guide).
The previous version of the MCP connector included tool configuration directly in the MCP server definition:
```python
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}
```
### Deprecated field descriptions
| Property | Type | Description |
|------------------------------------|---------|--------------------------------------------------------------------|
| `tool_configuration` | object | **Deprecated:** Use MCPToolset in the `tools` array instead |
| `tool_configuration.enabled` | boolean | **Deprecated:** Use `default_config.enabled` in MCPToolset |
| `tool_configuration.allowed_tools` | array | **Deprecated:** Use allowlist pattern with `configs` in MCPToolset |
## Compatibility
Supported platforms
- Claude APIBeta
- Claude Platform on AWSBeta
- Microsoft FoundryBeta
---
## Agents-Tools/agents-and-tools-mcp-tunnels-concepts-4259d94b65.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fconcepts)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# Architecture and components
Copy page
Canonical names for the parts of an MCP tunnel deployment, the two credential-provisioning modes, and the connection model.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This page defines the terms used throughout the [MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview) documentation. Several components appear under different names in configuration files, container images, and prose; the following tables give one canonical name for each and list the aliases you may encounter.
## Components
| Term | Definition | Also appears as |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Tunnel stack** | The two containers you run inside your network to attach to a tunnel: the proxy and cloudflared. One stack serves one tunnel and can be replicated across hosts for availability. With programmatic access, the setup component runs alongside the stack to provision credentials. | the stack, the MCP tunnel stack, the tunnel deployment, your deployment |
| **Proxy** | Anthropic's routing component. Terminates inner TLS, validates that upstream IPs fall within an allowed range, and routes each request to an upstream MCP server based on hostname. | `mcp-proxy` (image name, Compose service name, and Helm container name), `mcp-gateway` (container-internal config path `/etc/mcp-gateway/config.yaml` and Helm `gateway.config.*` values prefix) |
| **cloudflared** | Cloudflare's open-source tunnel connector. Initiates the outbound-only connections from your network to the tunnel edge and carries encrypted traffic between the edge and the proxy. Not related to a Managed Agent. | the outbound connector, the tunnel connector |
| **Setup component** | The `setup` binary, shipped inside the `mcp-proxy` image. With programmatic access it authenticates over Workload Identity Federation, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. Also provides `renew-cert`. | setup Job (the Helm pre-install hook), `setup` service (the Compose profile), setup hook, setup binary, setup CLI |
| **Tunnel edge** | The Cloudflare edge servers that cloudflared dials out to (IP ranges `198.41.192.0/19` and `2606:4700:a0::/44`, port 7844 TCP and UDP). The tunnel that runs over them is provisioned and controlled by Anthropic; Cloudflare operates the underlying network. | the edge, the Anthropic-operated tunnel edge |
| **Inner TLS** | A second TLS handshake carried inside the tunnel's plaintext WebSocket stream, between Anthropic's backend and your proxy. The proxy presents a server certificate signed by a CA you registered on the tunnel. Because only you hold the private key, the transport provider cannot read request or response payloads. | the inner TLS handshake |
| **Upstream MCP server** | An MCP server running in your private network that the proxy routes to. Each upstream is exposed as one subdomain under your tunnel domain. | upstream, routed MCP server, tunneled MCP server |
## Credential provisioning
The tunnel stack needs two credentials at runtime: the **tunnel token**, which authenticates cloudflared's outbound connection, and a **server certificate** signed by a CA registered on the tunnel, which the proxy presents during the inner TLS handshake. There are two ways to supply them, presented throughout this guide as a pair of tabs.
| Mode | How credentials reach the stack | Helm chart name | Tab label |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------------------------------|
| **Programmatic access** | The setup component authenticates to the Tunnels API through [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation), fetches the tunnel token, generates a CA and server certificate locally, and registers the CA. No long-lived secret is copied by hand. Requires a federation rule with the `workspace:manage_tunnels` scope. | Managed mode (`setup.enabled: true`, the default) | **With programmatic access** |
| **Manual** | You copy the tunnel token from the Claude Console, generate a CA and server certificate yourself (for example with `openssl`), register the CA in the Console, and supply the token and certificate to the stack as secrets. No setup component runs. | External mode (`setup.enabled: false`) | **Without programmatic access** |
These modes are also referred to as **the programmatic flow** and **the manual flow** in the deploy guides.
## Connection model
Two directions are at work in a tunnel, and they point opposite ways:
- **Connection direction:** cloudflared dials **outbound** from your network to the tunnel edge. Your firewall sees only egress on port 7844; no inbound port is opened.
- **Request direction:** once that connection is established, MCP requests travel **from Anthropic toward your network** over it, through cloudflared to the proxy, and on to the upstream MCP server.
The phrase "outbound-only" describes the connection, not the requests carried over it.
Inner TLS spans Anthropic's backend and your proxy. cloudflared and the tunnel edge sit between them on the wire but see only ciphertext; the proxy is the first place inside your network where MCP request payloads are readable.
## See also
- [MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview) for the security model and shared-responsibility table.
- [MCP tunnels reference](/docs/en/agents-and-tools/mcp-tunnels/reference) for proxy configuration fields, certificate requirements, and the setup component.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-console-61ec0ab65a.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fconsole)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# Manage tunnels in the Console
Copy page
Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This page covers the Console side of an MCP tunnels deployment: creating a tunnel, registering your CA certificate, retrieving the tunnel token, and attaching the [upstream MCP servers](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to an agent. [Deploy MCP tunnels with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) and [Deploy MCP tunnels with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose) cover running the [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) inside your network.
## Prerequisites
- **One or more MCP servers** running in your private network. The tunnel routes traffic to them; it does not host them. See [Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers) for examples you can deploy.
- **A Console role with the Manage tunnels permission**, so you can create and archive tunnels, rotate the token, and manage certificates. Organization admins and owners have it by default; custom roles and per-account grants can also include it. Roles without it have read-only access to the **MCP tunnels** page and tunnel details.
- **A way for your stack to authenticate to the Tunnels API.** Choose one:
- **[Programmatic access](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** Set up [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation) during tunnel creation so your stack mints short-lived API tokens from your identity provider, fetches the tunnel token, and generates and registers a CA certificate automatically. Requires permission to manage federation rules, a registered OIDC issuer, and a federation rule with the `workspace:manage_tunnels` scope.
- **[Manual](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. After creating the tunnel, [get the tunnel token](#get-the-connection-details), generate and [register a CA certificate](#add-a-ca-certificate) yourself, and supply the token and your server certificate to your tunnel stack as secrets.
## Create a tunnel
1. 1
### Open the MCP tunnels page
In the Console sidebar, go to **Manage \> MCP tunnels**. Tunnels are workspace-scoped; the new tunnel belongs to the workspace currently selected in the Console, so switch workspaces first if you want it elsewhere.
2. 2
### Name the tunnel
Click **New tunnel** and enter a name in the **Create tunnel** dialog. The name is required and identifies the tunnel in the list, on the detail page, and in the agent MCP server picker. A domain of the form `abcd1234.tunnel.anthropic.com` is assigned automatically.
3. 3
### Optionally set up programmatic access
If your role can manage federation rules, a **Set up programmatic access** toggle appears (off by default). If not, the Console shows a notice in its place and your tunnel stack uses the manual flow instead. The rest of the create flow is the same either way.
Programmatic access relies on [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation); read that page first if federation issuers, rules, and service accounts are unfamiliar. To turn the toggle on you need:
1. **A registered OIDC issuer** for the identity provider your stack presents tokens from (such as a Kubernetes cluster, AWS IAM, Google Cloud, or GitHub Actions). Register one under **Settings \> Workload identity \> Issuers** if your organization doesn't have one.
2. **A federation rule with the `workspace:manage_tunnels` scope.** Turning on the toggle reveals a **Federation rule** picker. Choose an existing rule with that scope, or click **Create federation rule** to create one inline.
3. **The rule's service account added to this workspace.** The Tunnels API authorizes against the service account's workspace memberships. If you're creating the tunnel in a workspace other than the organization's default, add the service account under **Settings \> Workspaces** and pass the workspace ID at deploy time (`api.wif.workspaceId` for Helm, `ANTHROPIC_WORKSPACE_ID` for Compose).
Skipping this step is fully supported; both deploy guides have a **Without programmatic access** tab.
4. 4
### Create the tunnel
Click **Create tunnel**. The Console provisions the tunnel and opens the detail page.
5. 5
### Record the deployment identifiers
Both deploy paths need:
- The **tunnel ID** (`tnl_...`), shown on the tunnel detail page.
- The **tunnel domain** (`abcd1234.tunnel.anthropic.com`), shown on the tunnel detail page. Used as the proxy's `tunnel_domain` and in the server certificate's SAN.
What else you need depends on the [credential-provisioning mode](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning):
| With programmatic access | Without programmatic access |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The **federation rule ID** (`fdrl_...`) of the rule you selected. The rule is org-level, not stored on the tunnel; find it under **Settings \> Workload identity \> Rules**. | The **tunnel token**, revealed with the eye icon next to **Token** on the detail page. Treat it as a secret. See [Get the connection details](#get-the-connection-details). |
| The **organization ID** (a UUID), shown under **Settings \> Organization**. | A **CA certificate** that you generate and [register on the tunnel](#add-a-ca-certificate). |
With programmatic access, your stack fetches the tunnel token through the Tunnels API, generates the CA and server certificate locally (the private key never leaves your environment), and registers only the CA's public certificate with Anthropic. You're still responsible for securing the private keys and renewing the server certificate before it expires.
Your organization can have up to 10 active tunnels. Creating a tunnel does not establish any connectivity; that happens once your stack dials in with the tunnel token and a CA certificate is registered.
## Get the connection details
Open the tunnel. The detail page shows a **Connection** section with the domain and token and a **Certificates** section.
| Field | Description |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Domain** | Copy the assigned `abcd1234.tunnel.anthropic.com` value. Your proxy's routes are subdomains of this domain. |
| **Token** | Click the eye icon (**Show token**) to fetch the tunnel token, then use the copy icon to copy it into your tunnel stack's secret store. Click **Rotate token** to invalidate the current token and issue a new one. |
Every reveal and rotation is recorded in your organization's [Compliance API](/docs/en/manage-claude/compliance-api) activity log. Rotation does not sever cloudflared connections that are already established, so you can rotate, redeploy with the new value, and let the old connections drain.
## Add a CA certificate
Anthropic verifies [inner TLS](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to your [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) against the CA certificates you register on the tunnel. A tunnel with no active certificates cannot accept connections, and does not appear in the agent MCP server picker until one is registered.
1. 1
### Find the Certificates section
On the tunnel's detail page, scroll to the **Certificates** section and click **Add certificate**.
2. 2
### Provide the certificate
Click **Choose file** to select a `.pem`, `.crt`, or `.cer` file, drag the file onto the text area, or paste the PEM block directly. The modal rejects private-key material and content that isn't a `-----BEGIN CERTIFICATE-----` block. The file must be 8 kB or smaller.
3. 3
### Add the certificate
Click **Add certificate**. The fingerprint and expiry appear in the certificate list, and the slot count on the section header increments.
A tunnel holds up to two active certificates so you can rotate without downtime: register the new certificate alongside the old one, redeploy your proxy with the new key pair, confirm traffic is flowing, then click **Revoke** on the old certificate's row. Revoked certificates remain visible in the list with a **Revoked** badge.
## Deploy the tunnel stack
The tunnel exists in the Console, but no traffic flows until the tunnel stack is running inside your network and dialed in with the tunnel token. Follow one of the deploy guides:
[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)
Run the tunnel stack on a single host. Both programmatic-access and manual flows.
[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)
Run the tunnel stack on a Kubernetes cluster. Both programmatic-access and manual flows.
## Use the tunnel in an agent
Once your stack is running and has one or more MCP servers configured, attach an upstream MCP server to a Managed Agent session. To call the same servers from the Messages API instead, see [Use the tunneled MCP servers](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers).
The picker only shows tunnels with at least one active certificate. A tunnel that still shows **Needs certificate** in the **MCP tunnels** list does not appear in the dropdown; register a CA certificate first. The picker is also workspace-scoped: it lists tunnels in the same workspace as the session, not other workspaces.
1. 1
### Open the New session modal
Go to **Managed Agents \> Sessions** and click **New session**.
2. 2
### Define an inline agent
In the agent picker, choose **Create new agent** so you can edit the MCP server list directly.
3. 3
### Add the MCP server
Click **+ MCP Server** and open the dropdown. Tunnels created in the current workspace appear at the top of the list, above the public connector catalog. Select the tunnel that fronts the server you want to reach.
4. 4
### Supply the routing
The card shows two optional fields: **Subdomain** (prefixed to the tunnel domain) and **Path** (appended after it). Fill in one or both, depending on how your proxy's routes are configured. The **Resolves to** line shows the full MCP server URL that the agent connects to.
The tunnel carries traffic; it does not authenticate to the upstream MCP server. Configure OAuth or bearer auth on the MCP server the same way as for any other MCP server.
## Archive a tunnel
Archiving immediately stops the tunnel from accepting connections and is permanent.
In the **MCP tunnels** list, open the row menu for the tunnel and choose **Archive**. Archived tunnels remain visible when you filter the list by **Archived** or **All**.
## Next steps
[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)
Install on a Kubernetes cluster using the Anthropic Helm chart.
[Security](/docs/en/agents-and-tools/mcp-tunnels/security)
Hardening guidance, credential rotation, and breach response.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-deploy-compose-12c9959bf8.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fdeploy-compose)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# Deploy MCP tunnels with Docker Compose
Copy page
Install the MCP tunnel stack on a VM using Docker Compose.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This guide deploys the [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as hardened containers on a single host. The same configuration can be replicated across multiple hosts for availability.
## Before you begin
You need:
- **A tunnel.** With programmatic access, the [setup component](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel.
- **A way for the host to authenticate to the Tunnels API.**
- **Programmatic access (recommended).** Turn on **Set up programmatic access** when creating the tunnel (or create the federation rule directly under **Settings \> Workload identity** if you're letting the setup component create the tunnel) so the setup component can authenticate through Workload Identity Federation. Record the federation rule ID (`fdrl_...`) and your organization ID.
- **Manual.** Skip programmatic access. You'll [get the tunnel token from the Console](/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, and [register the CA in the Console](/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).
- **A host with Docker and Docker Compose** installed. The manual flow also requires `openssl` (1.1.1 or later).
- **Outbound network connectivity** from the host to `api.anthropic.com` (443 TCP) and the [tunnel edge](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).
- **One or more MCP servers** running and reachable from the host on the addresses you'll configure under `routes`. If you don't have one yet, [use the sample server](#optional-use-a-sample-mcp-server).
## Optional: Use a sample MCP server
If you don't have an MCP server available for testing, use this minimal one:
```python
mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
EOF
```
The following Install steps `cd` into `mcp-tunnel/` and note where to add the corresponding service and route.
## Install
This guide provides one reference approach using Docker Compose. You are responsible for adapting it to meet your organization's security requirements.
With programmatic access
Without programmatic access
This path requires the host to have an OIDC identity provider (such as a cloud VM metadata server or SPIFFE). If it doesn't, use the **Without programmatic access** tab instead.
The setup component uses Workload Identity Federation to fetch the tunnel token, generate a CA and server certificate, and register the CA with Anthropic.
1. 1
### Prepare the deployment directory
``` shiki
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
sudo chown 65532:65532 data
```
The containers run as the non-root UID `65532` and need write access to `data/`.
2. 2
### Write docker-compose.yaml
The compose file pins images by SHA-256 digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation.
``` shiki
cat > docker-compose.yaml <<'EOF'
services:
setup:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
entrypoint: ["/setup"]
command:
- init
- --api-url=https://api.anthropic.com
- --output=dir:/data
- --token-version=1
environment:
- TUNNEL_ID
- ANTHROPIC_FEDERATION_RULE_ID
- ANTHROPIC_ORGANIZATION_ID
- ANTHROPIC_WORKSPACE_ID
- ANTHROPIC_IDENTITY_TOKEN
volumes:
- ./data:/data
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
profiles: ["setup"]
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
# Share the proxy's netns so localhost:8080 reaches it.
network_mode: "service:mcp-proxy"
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
EOF
```
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), append it as a service:
``` shiki
cat >> docker-compose.yaml <<'EOF'
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOF
```
3. 3
### Provision the tunnel
Set the identifiers. Leave `TUNNEL_ID` unset to have the setup component create a tunnel; set it to attach to an existing tunnel from the [Console](/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel):
``` shiki
# export TUNNEL_ID=tnl_... # set to attach to an existing tunnel
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
```
If your federation rule is scoped to a workspace other than your organization's default, also set `ANTHROPIC_WORKSPACE_ID=wrkspc_...`; the setup component uses the default workspace otherwise. An auto-created tunnel is created in that workspace.
Set `ANTHROPIC_IDENTITY_TOKEN` to an OIDC JWT from this host's identity provider. Follow the [WIF guide for your provider](/docs/en/manage-claude/workload-identity-federation#identity-providers) to register the issuer, set the rule's subject, and mint the token; the rule's audience must match the audience you request when minting.
Run the setup component:
``` shiki
docker compose run --rm setup
```
`setup init` is idempotent over `data/`: re-running it reuses the tunnel ID and CA already stored there and never creates a second tunnel. A new CA is generated and registered only when `data/` is empty or `TUNNEL_ID` has changed; in that case the cap of two active certificates applies, so revoke one in the Console first if both slots are filled.
See [Setup component authentication failures](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures) if it errors.
Retrieve your tunnel domain and export it for later steps:
``` shiki
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
echo "$TUNNEL_DOMAIN"
```
Workload Identity Federation tokens are short-lived (1 hour by default) and expire automatically; there is nothing to revoke after setup completes.
4. 4
### Write the proxy config
`tunnel_domain` is **required**: the [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) uses it to strip the domain suffix from incoming hostnames before looking up the subdomain in `routes`. `routes` is a flat map from subdomain to upstream URL, not a list.
``` shiki
cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
cert_file: /data/tls.crt
key_file: /data/tls.key
routes:
echo: http://hello-mcp:9000
EOF
```
The `echo:` route targets the [sample MCP server](#optional-use-a-sample-mcp-server); replace it with (or add) your own routes. See the [proxy configuration](/docs/en/agents-and-tools/mcp-tunnels/reference#proxy-configuration) reference for all available fields.
5. 5
### Start the deployment
``` shiki
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d
```
The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so the export must be repeated in every fresh shell and after a reboot.
For a multi-VM deployment, copy the `mcp-tunnel/` directory to each host, set `TUNNEL_TOKEN`, and run `docker compose up -d`. In the programmatic flow `TUNNEL_TOKEN` is `$(sudo cat data/tunnel-token)`; in the manual flow it's the value you copied from the Console. The same tunnel token and certificates work across all replicas.
## Verify the deployment
Verify end to end by calling an [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) from Anthropic's side: see [Use the tunneled MCP servers](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers). With the [sample MCP server](#optional-use-a-sample-mcp-server), the routed URL is `https://echo.<your-tunnel-domain>/mcp`. If verification fails, see [Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).
## Upgrades
Run the commands in this section from inside the `mcp-tunnel/` deployment directory.
### Rotate the tunnel token
With programmatic access, increment `--token-version` in the `setup` service command, set the Workload Identity Federation identifiers, mint a fresh OIDC JWT, and re-run the setup component:
```python
# Edit docker-compose.yaml: increment the integer in the setup service's
# --token-version argument (for example, --token-version=1 to
# --token-version=2). The setup binary refuses to rotate when the value
# hasn't changed.
# export TUNNEL_ID=tnl_... # set only if you set it during install
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_... # if your rule is workspace-scoped
# Re-mint ANTHROPIC_IDENTITY_TOKEN per the WIF provider guide for your
# environment (it will have expired since install).
export ANTHROPIC_IDENTITY_TOKEN=...
docker compose run --rm setup
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflared
```
The `--token-version` argument is edited in `docker-compose.yaml` rather than passed on the command line so the new value persists for future runs of the setup component. The setup component authenticates with Workload Identity Federation; there is no API token to revoke.
Without programmatic access, click **Rotate token** on the tunnel detail page in the Console, then update the `TUNNEL_TOKEN` environment variable on each host and restart cloudflared (`docker compose up -d cloudflared`).
Clicking **Rotate token** invalidates the current token immediately. Between that moment and updating `TUNNEL_TOKEN` on every host and restarting cloudflared, any host whose cloudflared restarts (crash, host reboot) cannot reconnect. Update each host promptly after rotating.
### Certificate renewal
You're responsible for monitoring expiry and renewing the server certificate before it expires.
With programmatic access:
```python
docker compose run --rm setup renew-cert --output=dir:/data
```
The CLI arguments replace the `setup` service's `command` (the `init` arguments) but keep its `entrypoint`, so this runs `/setup renew-cert --output=dir:/data`.
Pass `--renew-before=720h` to make the command a no-op when more than 30 days of validity remain. This makes it safe to run on a fixed schedule.
Without programmatic access, sign a new server certificate with your existing CA (the CA registered in the Console doesn't change) and replace `data/tls.crt`. Set `TUNNEL_DOMAIN` first if you're running this from a fresh shell.
```python
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
-subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
-CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
-out data/tls.crt -days 90 \
-extfile data/tls.ext
```
In either flow the proxy polls `tls.cert_file` and reloads it automatically, so no restart is required.
## Next steps
[Use the tunneled MCP servers](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers)
Attach an upstream MCP server to a Managed Agent or the Messages API.
[Security](/docs/en/agents-and-tools/mcp-tunnels/security)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)
Diagnose connectivity, TLS, and routing issues.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-deploy-helm-1a36bcc7af.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fdeploy-helm)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# Deploy MCP tunnels with Helm
Copy page
Install the tunnel stack on a Kubernetes cluster using the Anthropic Helm chart.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
The Anthropic Helm chart installs the [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as a single Deployment and attaches it to your tunnel: one the chart's setup hook creates for you, or an existing tunnel you created in the [Console](/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel).
## Before you begin
You need:
- **A tunnel.** With programmatic access, the chart's setup hook creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel; you'll also need its tunnel token and tunnel domain.
- **A way for the chart to authenticate to the Tunnels API.**
- **[Programmatic access](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** The [setup component](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) authenticates through Workload Identity Federation, fetches the tunnel token, generates a CA, registers it with Anthropic, and stores everything in a Secret. You'll need a federation rule scoped to `workspace:manage_tunnels`.
- **[Manual](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. You'll [get the tunnel token from the Console](/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate), and supply the credentials to the cluster as Secrets.
- **A Kubernetes cluster** you can deploy to with `helm` and `kubectl`. The **Without programmatic access** tab also uses `openssl` (1.1.1 or later).
- **Outbound network connectivity** from the cluster to `api.anthropic.com` (443 TCP) and the [tunnel edge](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).
- **One or more MCP servers** running and reachable from the cluster on the addresses you'll configure under `gateway.config.routes`. If you don't have one yet, [use the sample server](#optional-use-a-sample-mcp-server).
## Optional: Use a sample MCP server
If you don't have an MCP server available for testing, use this minimal one:
```python
kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: hello-mcp-src
data:
hello_server.py: |
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-mcp
spec:
replicas: 1
selector:
matchLabels: { app: hello-mcp }
template:
metadata:
labels: { app: hello-mcp }
spec:
containers:
- name: hello-mcp
image: python:3.13-slim
command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
volumeMounts:
- { name: src, mountPath: /app }
ports:
- { containerPort: 9000 }
volumes:
- name: src
configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
name: hello-mcp
spec:
selector: { app: hello-mcp }
ports:
- { port: 9000, targetPort: 9000 }
EOF
```
The Install steps that follow note where to add the corresponding route.
## Install
With programmatic access
Without programmatic access
The setup component exchanges the cluster's projected ServiceAccount token through your federation rule, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. A daily CronJob renews the server certificate as needed, so you don't handle any secrets by hand.
1. 1
### Set up Workload Identity Federation for the cluster
Follow [Use WIF with Kubernetes](/docs/en/manage-claude/wif-providers/kubernetes) to register your cluster's OIDC issuer and create a federation rule. The setup component runs under its own ServiceAccount in the release namespace; the exact name follows Helm's `fullname` convention, so for any release name other than `mcp-tunnel`, run `helm template <release> ... | grep -A2 'kind: ServiceAccount'` to confirm it before creating the rule. The rest of this guide assumes release name `mcp-tunnel` in namespace `mcp-tunnel`, where the ServiceAccount is `mcp-tunnel-setup`.
| Field | Value |
|----------|------------------------------------------------------|
| Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` |
| Audience | `api.anthropic.com` (the chart's default; no scheme) |
| Scope | `workspace:manage_tunnels` |
The chart's default audience is `api.anthropic.com` with no scheme, but the Console's federation-rule form suggests `https://api.anthropic.com`. The two must match byte-for-byte or authentication fails. Either set the rule's audience to `api.anthropic.com`, or set `api.wif.audience` in `values.yaml` to `https://api.anthropic.com`.
If the tunnel is in a workspace other than the organization's default, also add the rule's service account as a member of that workspace under **Settings \> Workspaces** (the Tunnels API authorizes against the service account's workspace memberships).
Note the rule's ID (`fdrl_...`); you'll set it as `api.wif.federationRuleId`.
The daily certificate-renewal CronJob uses a separate ServiceAccount (also derived from the Helm `fullname`) but does not call the Tunnels API; it renews the certificate locally and only needs Kubernetes RBAC, which the chart grants. The federation rule does not need to cover it.
2. 2
### Fetch the default values
``` shiki
helm show values \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 > values.yaml
```
3. 3
### Configure tunnel attachment and routes
Edit `values.yaml` and set the `api.wif.*` keys with the federation rule ID and organization ID, plus a `routes` entry for each [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components):
values.yaml
``` shiki
api:
wif:
federationRuleId: "fdrl_..."
organizationId: "00000000-0000-0000-0000-000000000000"
# Set when the tunnel is in a non-default workspace and the
# rule's service account is a member of that workspace.
# workspaceId: "wrkspc_..."
tunnel:
# Leave empty to have the setup hook create a tunnel during install.
# Set to attach to an existing tunnel from the Console.
id: ""
# Increment to rotate the tunnel token on the next upgrade.
# See the "Rotate the tunnel token" section.
tokenVersion: "1"
gateway:
config:
routes:
docs: http://docs-mcp.internal:8080
search: http://search-mcp.internal:8080
```
With these routes, Claude reaches the servers at `docs.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here per [Upstream IP validation](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.
4. 4
### Review the rendered manifests
Render the chart and review the output according to your organization's vetting practices:
``` shiki
helm template mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml > rendered.yaml
```
5. 5
### Install
``` shiki
helm install mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
--namespace mcp-tunnel --create-namespace \
-f values.yaml
```
The setup component runs as a Helm pre-install hook Job, so `helm install` blocks until it completes. On success Helm deletes the Job automatically. If `helm install` fails with a hook error, see [Setup component authentication failures](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures).
When `tunnel.id` is empty, the setup component creates the tunnel in the workspace your federation rule targets (the organization's default workspace unless you set `api.wif.workspaceId`) and stores its ID and domain in the `mcp-tunnel` Secret. Find the domain you'll need for [verification](#verify-the-deployment) on the tunnel's detail page in the Console under **Manage \> MCP tunnels**, or read it from the Secret:
``` shiki
kubectl -n mcp-tunnel get secret mcp-tunnel \
-o jsonpath='{.data.tunnel-domain}' | base64 -d
```
Re-running the setup component (during [upgrades](#upgrades) or [token rotation](#rotate-the-tunnel-token)) reuses the tunnel ID stored in this Secret; it never creates a second tunnel.
The `api.wif.*` values are identifiers, not secrets, so storing them in Helm release-history Secrets is not a risk. The sensitive data at rest is the `mcp-tunnel` Secret the setup component creates, which holds the tunnel token and TLS private keys. Apply your organization's standard practices for protecting Kubernetes Secrets to this namespace.
## Verify the deployment
Verify end to end from Anthropic's side: use `https://<route>.<your-tunnel-domain>/<path>` in a Managed Agent session or a Messages API request, where `<route>` is a key from `gateway.config.routes` and `<path>` is whatever the upstream MCP server serves at. With the [sample MCP server](#optional-use-a-sample-mcp-server), that's `https://echo.<your-tunnel-domain>/mcp`. See [Use the tunneled MCP servers](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) for the request shapes.
If that fails, check the pod logs (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` and `-c cloudflared`) and consult [Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).
## Optional configuration
### Restrict egress with NetworkPolicy
Ingress to the proxy pod is denied by default (`networkPolicy.ingress.enabled: true`). To additionally restrict pod egress, set `networkPolicy.egress.enabled: true` and populate `networkPolicy.egress.mcpServers` with pod label selectors or CIDR ranges that cover your upstream MCP servers. Egress from cloudflared to the tunnel edge is allowed separately through `networkPolicy.egress.cloudflaredEgressCIDRs`.
### Tune the proxy
Fields under `gateway.config.*` pass through to the proxy configuration file. Common adjustments include `upstream.allowed_ips`, `log_level`, and `upstream.tls`. See the [proxy configuration](/docs/en/agents-and-tools/mcp-tunnels/reference#proxy-configuration) reference for the full field list. The chart always sets `listen_addr`, `tls.cert_file`, and `tls.key_file`; setting them in `gateway.config` has no effect.
### Supply your own OIDC token
By default the chart projects a Kubernetes ServiceAccount token for the setup component. To use a token from a different identity provider (such as [SPIFFE](/docs/en/manage-claude/wif-providers/spiffe), Vault, or a cloud-SDK sidecar), mount it with `setup.extraVolumes` and `setup.extraVolumeMounts`. Then point `api.wif.tokenFile` at the mount path. The chart sets `ANTHROPIC_IDENTITY_TOKEN_FILE` to that path, and the setup component reads the token from there.
## Upgrades
Always pass `--version` to `helm upgrade` so you don't pull a newer chart unexpectedly.
### Upgrade from chart 1.x
Chart 2.0.0 moves the tunnel ID from `api.wif.tunnelId` to `tunnel.id`. Before upgrading, edit your `values.yaml`: move the `tnl_...` value to `tunnel.id` and remove `api.wif.tunnelId`. Leaving `tunnel.id` unset is safe (the setup component reuses the tunnel ID already stored in the `mcp-tunnel` Secret on re-run), but the explicit move keeps your `values.yaml` accurate. Also update your federation rule's scope from `org:manage_tunnels` to `workspace:manage_tunnels` in the Console.
### Change configuration
For routine changes such as routes, replica count, or NetworkPolicy:
```python
helm upgrade mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml
```
Maintain a complete `values.yaml` rather than relying on `--reuse-values`. Helm's deep-merge behavior can silently fail to remove deleted routes.
### Rotate the tunnel token
With programmatic access, increment `tunnel.tokenVersion` in `values.yaml` and upgrade with `--set setup.force=true`. The setup component only re-runs on upgrades when forced:
```python
helm upgrade mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml \
--set setup.force=true
```
The setup component authenticates with Workload Identity Federation; there is no API token to revoke.
Without programmatic access, click **Rotate token** on the tunnel detail page in the Console, then update the `mcp-tunnel-token` Secret:
```python
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
--from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel
```
Clicking **Rotate token** invalidates the current token immediately. Until the Secret is updated and the rollout completes, any pod that restarts with the old token (eviction, node drain, OOM) cannot reconnect. Update the Secret promptly after rotating; for stricter availability requirements, use programmatic access so the chart handles the rotation atomically.
### Certificate renewal
The chart provides automation, but you remain responsible for monitoring expiry and confirming renewal completes.
With programmatic access, certificate renewal is automatic. The chart deploys a CronJob (named after the Helm `fullname`, suffixed `-cert-renew`) that runs `setup renew-cert` daily (at `serverCert.cronSchedule`, default `0 0 * * *` UTC). The job is a no-op unless the certificate is within `serverCert.renewBefore` of expiry (default 30 days). Renewal is local: the job signs a fresh certificate with the CA already stored in the Secret, makes no API calls, and only needs the Kubernetes RBAC the chart grants. The proxy hot-reloads the certificate from the Secret mount, so no Deployment restart is needed.
Without programmatic access there is no CronJob. From inside the `mcp-tunnel/` directory you kept after install, sign a fresh server certificate with the existing CA (do not regenerate the CA):
```python
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
-subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
-CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
-out data/tls.crt -days 90 -extfile data/tls.ext
kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
--from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
--dry-run=client -o yaml | kubectl apply -f -
```
The proxy hot-reloads the certificate from the Secret mount.
## Next steps
[Use the tunneled MCP servers](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers)
Attach an upstream MCP server to a Managed Agent or the Messages API.
[Security](/docs/en/agents-and-tools/mcp-tunnels/security)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)
Diagnose connectivity, TLS, and routing issues.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-overview-4bc641a728.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Foverview)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# MCP tunnels
Copy page
Securely connect Claude to MCP servers running in your private network without opening inbound ports or exposing services to the public internet.
Copy page
MCP tunnels let you connect Claude to Model Context Protocol (MCP) servers that run inside your private network. Traffic flows over an outbound-only connection, so you don't need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic's IP ranges on your origin.
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them. They are provided "as-is" without any uptime, support, or continuity commitment, and they depend on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time.
For Zero Data Retention and HIPAA BAA eligibility, see [API and data retention](/docs/en/manage-claude/api-and-data-retention#feature-eligibility).
## How it works
The [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) is two components that run inside your network:
- **[cloudflared](/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Cloudflare's open-source tunnel connector. It initiates outbound-only connections to the [tunnel edge](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and carries encrypted traffic from Anthropic to your proxy.
- **[Proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Anthropic's routing component. It terminates [inner TLS](/docs/en/agents-and-tools/mcp-tunnels/concepts#components), validates that upstream IPs fall within an allowed range, and routes each request to the correct [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) based on hostname.
Each MCP server you expose gets a hostname under your tunnel domain (for example, `docs.<your-tunnel-domain>`). You attach these hostnames to a Managed Agent session in the Claude Console, or pass them to the Messages API through the [MCP connector](/docs/en/agents-and-tools/mcp-connector).
## Prerequisites
Before deploying, make sure you have:
- A deployment target: a Kubernetes cluster, or a VM with Docker and Docker Compose.
- A tunnel. Create one in the Claude Console (see [Create a tunnel](/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel)) or through the API; the Helm chart's setup hook can also create one for you during install.
- A way for your stack to authenticate to the Tunnels API. Choose one:
- **[Programmatic access](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** Set up [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation) when you create the tunnel. Your stack mints short-lived API tokens from your identity provider, fetches the tunnel token, and generates and registers a CA certificate automatically. Requires permission to manage federation rules, a registered OIDC issuer, and a federation rule with the `workspace:manage_tunnels` scope.
- **[Manual](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Supply static credentials yourself: the tunnel token from the Console and a server certificate signed by a CA you register there. See [Get the connection details](/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details) and [Add a CA certificate](/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).
- One or more MCP servers running in your private network. See [Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers) for examples.
- Outbound connectivity as listed under [Network requirements](#network-requirements).
### Network requirements
| Component | Destination | Port / protocol | Used during |
|-----------------|------------------------------------------------------|------------------|---------------------------------|
| Setup component | `api.anthropic.com` | 443 TCP | Provisioning and token rotation |
| cloudflared | Tunnel edge (`198.41.192.0/19`, `2606:4700:a0::/44`) | 7844 TCP and UDP | Runtime |
| Proxy | Your upstream MCP servers | As configured | Runtime |
## Security model
### Security layers
Three independent layers protect every request:
| Layer | Protects against |
|-----------------------------------------------------------------------------|--------------------------------------------------------------------------|
| Outer mTLS between Anthropic and the transport provider, with IP validation | Unauthorized clients reaching the tunnel |
| Inner TLS from Anthropic's back end to your proxy | Payload inspection by the transport provider or any network intermediary |
| OAuth on each MCP server | Unauthorized use of MCP tools by authenticated tunnel traffic |
The tunnel transport runs on Cloudflare's network. Because the proxy terminates inner TLS using a certificate that only you hold, Cloudflare cannot read request or response payloads. Anthropic does not connect to a tunnel until a CA certificate is registered, so payloads are always encrypted when they cross Cloudflare's network. Cloudflare does receive connection metadata; see [What the transport provider can observe](#what-the-transport-provider-can-observe).
### Shared responsibility model
| Anthropic handles | Your organization handles |
|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| Tunnel access control | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies (including Cloudflare's) |
| Validating your CA certificate before connecting to your proxy | Adherence to the deployment guidance on these pages |
| Ensuring Claude only sends requests to tunnels owned by your organization | Securing tunnel tokens and TLS private keys |
| | Managing the server certificate and renewing it before it expires |
| | Configuring OAuth on each MCP server |
| | Restricting network access for the proxy and MCP servers |
| | Notifying Anthropic if you suspect a breach |
If an attacker obtains your tunnel token **and** one of your TLS private keys, they could impersonate your proxy and read MCP request payloads. Treat both as high-value secrets. See [MCP tunnels security](/docs/en/agents-and-tools/mcp-tunnels/security) for hardening guidance.
### What the transport provider can observe
Cloudflare provides the outbound transport. It cannot read MCP request or response payloads, but it does receive the following connection metadata:
- the egress IP address of the host running cloudflared
- a cloudflared host fingerprint
- connection timing and byte-volume
- the `*.tunnel.anthropic.com` subdomain assigned to your tunnel
Anthropic's agreement with Cloudflare restricts Cloudflare's use of this telemetry. Cloudflare acts as a subprocessor for this research preview.
## Deploy a tunnel
If you're new to MCP tunnels, start with the quickstart to get a working tunnel locally before configuring a production deployment.
[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)
The shortest path to a working tunnel: Docker Compose with a sample MCP server.
[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)
Install on a Kubernetes cluster using the Anthropic Helm chart.
[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)
Install on a VM using Docker Compose.
Choosing between them:
- **Deployment target**
- **Helm** when deploying to Kubernetes.
- **Docker Compose** for a single host or local testing.
- **Authentication for setup**
- **Programmatic access** (through Workload Identity Federation) when you have an OIDC identity provider such as a Kubernetes cluster, cloud IAM, or SPIFFE.
- **Manual credentials** when you don't, or when you're testing.
## Use the tunneled MCP servers
Once your tunnel is active (it has an active CA certificate and your tunnel stack is connected), the upstream MCP servers are reachable from Claude Managed Agents and the Messages API.
MCP tunnels created through the Console are not available as connectors in claude.ai.
In both cases, the tunnel carries encrypted traffic to your MCP server but does not authenticate to it. If the upstream MCP server requires its own authentication (OAuth, bearer token), supply it the same way you would for any other MCP server; it is independent of the tunnel.
### Managed Agents (Console)
1. In **Managed Agents \> Sessions**, create a session and choose **Create new agent** so you can edit the MCP server list.
2. Click **+ MCP Server** and open the dropdown. Tunnels in the session's workspace that have at least one active certificate appear at the top of the list, above the public connector catalog.
3. Select the tunnel and supply the **Subdomain** that your proxy routes to a specific MCP server, and the **Path** the upstream MCP server expects. The **Resolves to** line shows the exact URL.
### Messages API
Pass the upstream MCP server's URL in the `mcp_servers` array, the same way as any other remote MCP server. The request body and `anthropic-beta` header follow the standard [MCP connector](/docs/en/agents-and-tools/mcp-connector) format; only the `url` is tunnel-specific. The following example uses the MCP connector's `mcp-client` beta header, which is separate from the `mcp-tunnels` beta used by the [Tunnels API](/docs/en/agents-and-tools/mcp-tunnels/reference). Make the request in the workspace the tunnel was created in by using an API key for that workspace or, if your key has access to multiple workspaces, by setting the [`anthropic-workspace-id` header](/docs/en/manage-claude/authentication#select-a-workspace) to that workspace.
The URL's host is `<subdomain>.<your-tunnel-domain>`. The path depends on your upstream MCP server, not the tunnel: FastMCP's `streamable-http` transport serves at `/mcp`, and other servers may use `/` or a custom path (check the server's documentation). The proxy forwards the path untouched.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1000,
messages=[{"role": "user", "content": "Use the hello tool to greet tunnel."}],
mcp_servers=[
{
"type": "url",
"url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
"name": "echo",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "echo"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
For authenticating to the upstream MCP server (`authorization_token`) and other `mcp_servers` options, see [MCP connector](/docs/en/agents-and-tools/mcp-connector).
## Next steps
[Security](/docs/en/agents-and-tools/mcp-tunnels/security)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)
Diagnose connectivity, TLS, and routing issues.
[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Proxy config fields, the Tunnels API, certificate requirements, and the setup component.
[MCP connector](/docs/en/agents-and-tools/mcp-connector)
Use tunneled servers from the Messages API.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-quickstart-d84e85df16.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fquickstart)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# MCP tunnels quickstart
Copy page
Connect Claude to a private MCP server using a local Docker Compose deployment.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This quickstart takes you from zero to Claude calling a private MCP server through a tunnel. It uses Docker Compose with [manual](/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) credential provisioning, which is the shortest path for local testing. For production deployments, see [Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) or [Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose).
## What you'll build
A two-container [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (the [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and [cloudflared](/docs/en/agents-and-tools/mcp-tunnels/concepts#components)) plus a sample MCP server running alongside it. When everything is running, the sample server is reachable from Claude at `https://echo.<your-tunnel-domain>/mcp` even though nothing is listening on a public port.
## What you need
- [Docker and Docker Compose](https://docs.docker.com/get-docker/) on a machine with outbound internet access.
- A role in the [Claude Console](https://platform.claude.com) that can manage MCP tunnels. See the [Console guide prerequisites](/docs/en/agents-and-tools/mcp-tunnels/console#prerequisites).
- [OpenSSL](https://openssl-library.org/source/) 1.1.1 or later. Preinstalled on macOS and most Linux distributions; on Windows, install it separately (the `openssl` binary must be on your `PATH`).
1. 1
### Create a tunnel
In the Claude Console sidebar, go to **Manage \> MCP tunnels** and click **New tunnel**. Give it a name. Leave **Set up programmatic access** off; this quickstart uses manual credential provisioning.
After it's created, open the tunnel. Copy two values from the **Connection** section:
- **Domain** (looks like `abcd1234.tunnel.anthropic.com`)
- **Token** (click the eye icon, then copy)
2. 2
### Set up the deployment directory
macOS / Linux
Windows (PowerShell)
``` shiki
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE # from step 1
export TUNNEL_TOKEN='eyJ...' # from step 1
```
3. 3
### Generate a CA and server certificate
The proxy terminates [inner TLS](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) using a certificate signed by a CA you control. Generate both:
macOS / Linux
Windows (PowerShell)
``` shiki
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout data/ca.key -out data/ca.crt \
-days 3650 -subj "/CN=mcp-tunnel-ca" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-addext "subjectKeyIdentifier=hash"
cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF
openssl req -newkey rsa:2048 -nodes \
-keyout data/tls.key -out /tmp/server.csr \
-subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
-CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
-out data/tls.crt -days 90 -extfile data/tls.ext
chmod 644 data/tls.key
```
Back in the Console, on the tunnel detail page, click **Add certificate** and upload `data/ca.crt` (or paste its contents). The tunnel status flips to **Active**.
4. 4
### Write the sample MCP server
macOS / Linux
Windows (PowerShell)
``` shiki
cat > hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
EOF
```
5. 5
### Write the proxy config and compose file
macOS / Linux
Windows (PowerShell)
``` shiki
cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
cert_file: /data/tls.crt
key_file: /data/tls.key
routes:
echo: http://hello-mcp:9000
EOF
cat > docker-compose.yaml <<'EOF'
services:
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
network_mode: "service:mcp-proxy"
restart: unless-stopped
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOF
```
6. 6
### Start it
macOS / Linux
Windows (PowerShell)
``` shiki
docker compose up -d
docker compose logs mcp-proxy | grep "route configured"
docker compose logs cloudflared | grep "Registered tunnel connection"
```
You should see one `route configured` line for `echo` and four `Registered tunnel connection` lines. The containers take a few seconds to start; rerun the log commands if they come back empty.
7. 7
### Call it from Claude
In the Console, go to **Managed Agents \> Sessions** and create a session. In the agent picker choose **Create new agent**, give the agent a name, and keep the pre-filled model. Click **+ MCP Server**, select your tunnel, set **Subdomain** to `echo` and **Path** to `mcp`. Then ask:
> Use the hello tool to greet tunnel.
You should see a tool call followed by its result.
## Next steps
The tunnel is verified end to end. To swap in your own MCP server, add it to `docker-compose.yaml` (or run it on the same Docker network), add a route for it in `config/mcp-proxy.yaml`, then restart the proxy (`docker compose restart mcp-proxy`).
For production deployments:
[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)
Hardened single-host deployment, with or without programmatic access.
[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)
Kubernetes deployment with automatic credential management.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-reference-8fe3088fe2.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Freference)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# MCP tunnels reference
Copy page
Proxy configuration fields, the Tunnels REST API, certificate requirements, and the setup component.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
## Proxy configuration
The [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) reads its configuration from `/etc/mcp-gateway/config.yaml` (Compose) or the rendered ConfigMap (Helm, populated from `gateway.config.*`).
| Field | Description | Default |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `listen_addr` | Address and port to listen on. | Required |
| `log_level` | Logging verbosity: `debug`, `info`, `warn`, or `error`. | `info` |
| `shutdown_timeout` | How long to wait for in-flight requests during graceful shutdown. | `30s` |
| `tunnel_domain` | Base domain assigned to the tunnel. When set, route lookup strips this suffix from incoming hostnames so `routes` keys can be bare subdomains (`wiki`). When empty, `routes` keys must be exact full hostnames. | Required when `routes` keys are bare subdomains |
| `tls.cert_file` | Path to the server TLS certificate. | Required |
| `tls.key_file` | Path to the server TLS private key. | Required |
| `routes` | Map of subdomain or full hostname to upstream URL. See [Route matching](#route-matching). | Required |
| `upstream.allowed_ips` | IPv4 CIDR ranges or single addresses the proxy is permitted to connect to. Mutually exclusive with `disable_ip_validation`. | RFC1918 private ranges |
| `upstream.disable_ip_validation` | Disable upstream IP validation entirely. Mutually exclusive with `allowed_ips`. | `false` |
| `upstream.tls.ca_file` | CA bundle for validating upstream TLS. | None |
| `upstream.tls.include_system_cas` | Also trust the system CA bundle for upstream TLS. | `false` |
For `https://` upstream routes, set at least one of `upstream.tls.ca_file` or `upstream.tls.include_system_cas`; otherwise the proxy has no trust anchor for the upstream certificate.
### Route matching
`routes` is a flat string map (`map[string]string`), not a list. The proxy looks up the incoming hostname by exact match first, then by stripping the `tunnel_domain` suffix and matching the remaining subdomain. The match considers only the hostname; the request path and query string are forwarded to the [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) unchanged.
Each upstream value must be exactly `scheme://host:port`. The port is mandatory. Including a path is rejected at config load with `invalid upstream (must be scheme://host:port)`.
## Tunnels API
The Tunnels REST API lives at `/v1/tunnels` and supports creating, listing, and archiving tunnels, registering CA certificates, and revealing or rotating the tunnel token. See the [Tunnels API reference](/docs/en/api/beta/tunnels/list) for all endpoints, request and response schemas, and examples.
The previous Admin API surface at `/v1/organizations/tunnels` (beta header `mcp-tunnels-2026-05-19`, scope `org:manage_tunnels`) continues to work during a migration window and remains documented in the [Admin API reference](/docs/en/api/beta/organization/mcp_tunnels) with a deprecation notice. To migrate, update the path to `/v1/tunnels`, the beta header to `mcp-tunnels-2026-06-22`, and your WIF token scope to `workspace:manage_tunnels`.
All MCP tunnels endpoints require a bearer token with the `workspace:manage_tunnels` scope obtained through [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation). Admin API keys are not accepted.
Required headers on every request:
| Header | Value |
|---------------------|--------------------------------------------|
| `Authorization` | `Bearer <token>` (the WIF-exchanged token) |
| `anthropic-version` | `2023-06-01` |
| `anthropic-beta` | `mcp-tunnels-2026-06-22` |
## Certificate requirements
The [setup component](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) generates compliant certificates automatically. These requirements apply only if you issue certificates through your own PKI.
### CA certificate
Upload with `POST /v1/tunnels/{tunnel_id}/certificates`. A tunnel can hold up to two active CA certificates at a time, which allows zero-downtime rotation.
- PEM-encoded, single certificate, up to 8 kB.
- `BasicConstraints` extension present with `CA:TRUE`, marked critical.
- `SubjectKeyIdentifier` extension present.
- `KeyUsage` includes `keyCertSign`.
- Within its validity period.
- RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.
### Server certificate
Presented by the proxy during [inner TLS](/docs/en/agents-and-tools/mcp-tunnels/concepts#components).
- Signed directly by a registered CA (no intermediates).
- `AuthorityKeyIdentifier` extension present and matching the CA's `SubjectKeyIdentifier`.
- Subject Alternative Name includes a DNS name matching `<route>.<tunnel-domain>`. A wildcard `*.<tunnel-domain>` covers all routes.
- If the `ExtendedKeyUsage` extension is present, it includes `serverAuth`.
- Within its validity period.
- RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.
The setup component generates an ECDSA P-256 CA with five-year validity and an RSA 4096-bit server certificate with a wildcard SAN and 90-day validity.
## Setup component
The setup component ships inside the `mcp-proxy` image as the `setup` binary. Run it with `docker compose run --rm setup <subcommand>` (Compose) or rely on the chart's hooks and CronJobs (Helm).
### `setup init`
Attaches to an existing tunnel (or creates one when no tunnel ID is supplied), then generates a CA and server certificate, registers the CA, retrieves the tunnel token, and writes all outputs to the destination.
| Flag | Description | Default |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `--api-url` | Claude API base URL. Also read from `API_URL`. | Required |
| `--tunnel-id` | Tunnel ID to attach to (`tnl_...`). Also read from `TUNNEL_ID`. When omitted, a new tunnel is created; a tunnel ID already stored in the output is reused on re-runs. | None (create a tunnel) |
| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:<release>`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |
| `--cert-duration` | Server certificate validity period. | `2160h` (90 days) |
| `--token-version` | Change-detection string. A new value triggers token rotation on re-run. The Helm chart and the Compose example both pass `1` as the initial value. | None |
The command authenticates through [Workload Identity Federation](/docs/en/manage-claude/workload-identity-federation). It reads `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (optional), and exactly one of `ANTHROPIC_IDENTITY_TOKEN_FILE` or `ANTHROPIC_IDENTITY_TOKEN`. See the [WIF reference](/docs/en/manage-claude/wif-reference) for the current semantics of these variables; the setup component derives the service account from the federation rule, so it does not require `ANTHROPIC_SERVICE_ACCOUNT_ID` separately.
### `setup renew-cert`
Issues a new server certificate signed by the stored CA. Makes no API calls.
| Flag | Description | Default |
|-------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:<release>`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |
| `--cert-duration` | New certificate validity period. | `2160h` (90 days) |
| `--renew-before` | Skip renewal if the existing certificate has more than this duration remaining. | `0` (always renew) |
Setting `--renew-before=720h` makes the command a no-op when more than 30 days of validity remain, so it's safe to run on a fixed schedule.
---
## Agents-Tools/agents-and-tools-mcp-tunnels-security-bc2f275195.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fsecurity)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# MCP tunnels security
Copy page
Hardening guidance, credential rotation, breach response, and teardown for MCP tunnel deployments.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
The tunnel architecture provides strong defaults (outbound-only connectivity, end-to-end encryption, and IP validation), but the overall security of your [tunnel stack](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) also depends on how you configure and operate it. This page covers recommended hardening, breach response, and how to decommission a tunnel.
## Best practices
- **Require OAuth on every MCP server.** Configure each [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to require OAuth as described in the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). OAuth provides defense in depth on top of the tunnel's transport authentication and enables user-level authorization at the data layer.
- **Enable SSO for your organization.** Tunnels, federation rules, and service accounts are managed in the Claude Console. SSO enforces your identity provider's session controls on the admins who can change them.
- **Restrict `upstream.allowed_ips`.** Use the smallest CIDR ranges that cover your MCP servers. This is the [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components)'s primary SSRF defense.
- **Monitor logs.** Alert on warnings, errors, and unusual traffic patterns from the tunnel stack.
- **Rotate credentials.** Rotate the server certificate and tunnel token on a regular schedule, and immediately if you suspect compromise.
- **Keep images updated.** Track new proxy releases and pin images by SHA-256 digest.
- **Limit network reach.** The proxy and [cloudflared](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) should only be able to reach the destinations listed in the [network requirements](/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements). Use NetworkPolicy (Kubernetes) or host firewall rules (Compose).
- **Limit MCP server scope.** Each server should expose only the tools and data required for its purpose.
- **Protect credentials at rest.** Apply your organization's secrets-management practices to private keys and tunnel tokens.
## Respond to a suspected breach
If you believe your tunnel token, TLS keys, or proxy host has been compromised:
1. 1
### Stop the tunnel stack
Helm
Docker Compose
``` shiki
helm uninstall mcp-tunnel -n mcp-tunnel
```
2. 2
### Detach the upstream MCP servers
Remove the upstream MCP servers from any Managed Agent sessions that use them, and stop passing their URLs in the `mcp_servers` block of Messages API requests.
3. 3
### Archive the tunnel
Archiving invalidates the tunnel token and detaches the domain. In the Console, [archive the tunnel](/docs/en/agents-and-tools/mcp-tunnels/console#archive-a-tunnel) from the **MCP tunnels** list. To archive over the API instead, see [Archive a tunnel](/docs/en/api/beta/tunnels/archive).
4. 4
### Contact Anthropic
Report the suspected compromise to Anthropic support.
5. 5
### Rotate downstream credentials
Re-provision a fresh tunnel and rotate any OAuth tokens that the affected MCP servers issued.
6. 6
### Review logs before restoring service
Inspect proxy, cloudflared, and MCP server logs for the window of suspected compromise before bringing the new tunnel online.
## Tear down a tunnel
Follow these steps to decommission a tunnel and remove all stored credentials.
1. 1
### Stop the tunnel stack
Helm
Docker Compose
``` shiki
helm uninstall mcp-tunnel -n mcp-tunnel
```
2. 2
### Archive the tunnel
In the Console, [archive the tunnel](/docs/en/agents-and-tools/mcp-tunnels/console#archive-a-tunnel) from the **MCP tunnels** list.
3. 3
### Remove stored credentials
Helm
Docker Compose
With programmatic access, the setup component created a single Secret named after the release. Without programmatic access, you created `mcp-tunnel-token` and `mcp-tunnel-cert` yourself. Delete whichever apply:
``` shiki
kubectl -n mcp-tunnel delete secret \
mcp-tunnel mcp-tunnel-token mcp-tunnel-cert \
--ignore-not-found
```
---
## Agents-Tools/agents-and-tools-mcp-tunnels-troubleshooting-f51de6da4b.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Ftroubleshooting)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
[Overview](/docs/en/agents-and-tools/mcp-tunnels/overview)[Architecture and components](/docs/en/agents-and-tools/mcp-tunnels/concepts)[Quickstart](/docs/en/agents-and-tools/mcp-tunnels/quickstart)[Manage in the Console](/docs/en/agents-and-tools/mcp-tunnels/console)[Deploy with Helm](/docs/en/agents-and-tools/mcp-tunnels/deploy-helm)[Deploy with Docker Compose](/docs/en/agents-and-tools/mcp-tunnels/deploy-compose)[Security](/docs/en/agents-and-tools/mcp-tunnels/security)[Troubleshooting](/docs/en/agents-and-tools/mcp-tunnels/troubleshooting)[Reference](/docs/en/agents-and-tools/mcp-tunnels/reference)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP tunnels
# Troubleshoot MCP tunnels
Copy page
Diagnose connectivity, TLS, IP validation, and OAuth routing issues in a tunnel stack.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
A request through the tunnel can fail at one of three layers; diagnose them in order: the outbound connection to the [tunnel edge](/docs/en/agents-and-tools/mcp-tunnels/concepts#components), the [inner TLS](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) from Anthropic to your [proxy](/docs/en/agents-and-tools/mcp-tunnels/concepts#components), then routing and IP validation toward the [upstream MCP server](/docs/en/agents-and-tools/mcp-tunnels/concepts#components).
## Quick reference
| Symptom | Cause | Fix |
|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| Tunnel doesn't appear in the agent **+ MCP Server** picker | The picker only lists tunnels in the session's workspace that have at least one active certificate. | Register a CA certificate, or open the session in the workspace the tunnel was created in. |
| Caller sees HTTP 500; [cloudflared](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) logs `No ingress rules were defined` | cloudflared has no local target. | Add `--url http://localhost:8080` and `network_mode: "service:mcp-proxy"` to the cloudflared service. |
| Proxy logs `no route for host` | `tunnel_domain` doesn't match the assigned domain, or `config.yaml` was edited without restarting. | Set `tunnel_domain` to the exact domain shown on the tunnel detail page, then restart the proxy (`docker compose restart mcp-proxy`). |
| Proxy logs `IP validation failed: <ip> is not a private address` | Upstream MCP server resolves outside RFC1918. | See [Upstream IP validation](#upstream-ip-validation). |
| Proxy exits with `cannot unmarshal !!seq into map[string]string` | `routes` is a YAML list. | Use `routes: { name: http://host:port }`. |
| Proxy exits with `open /data/tls.key: permission denied` | The key is `0600`; the proxy container runs non-root. | `chmod 644 data/tls.key`. |
| `curl https://<proxy>:8080` fails with `wrong version number` | Expected; the listener is plaintext WebSocket. TLS happens inside the WS stream. | Verify through a [Managed Agent or the Messages API](/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) instead. |
The following sections cover failures that need more than a one-line fix.
## OAuth fails behind a source-IP allowlist
OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's backend from reaching `/token`, `/register`, and the discovery endpoints. If you'd rather not allowlist Anthropic's egress ranges, you can route the backend-to-backend OAuth calls through the tunnel while keeping the browser-facing `/authorize` endpoint on your existing public hostname.
1. 1
### Add a proxy route for the authorization server
``` shiki
routes:
mcp: http://your-mcp-server:8080
auth: http://your-auth-server:8080
```
Restart the proxy after editing `routes` (`docker compose restart mcp-proxy`, or `helm upgrade`).
2. 2
### Serve split-endpoint discovery metadata
Your authorization server's `/.well-known/oauth-authorization-server` response should point `authorization_endpoint` at your existing allowlisted hostname and everything else at the tunnel:
``` shiki
{
"issuer": "https://auth.<tunnel-domain>",
"authorization_endpoint": "https://<your-allowlisted-host>/authorize",
"token_endpoint": "https://auth.<tunnel-domain>/token",
"registration_endpoint": "https://auth.<tunnel-domain>/register",
"code_challenge_methods_supported": ["S256"]
}
```
3. 3
### Point the MCP server at the tunnel issuer
Your MCP server's `/.well-known/oauth-protected-resource` response should reference the tunnel hostname as its authorization server:
``` shiki
{
"resource": "https://mcp.<tunnel-domain>",
"authorization_servers": ["https://auth.<tunnel-domain>"]
}
```
With this configuration, the user's browser hits `/authorize` on your existing hostname (which your allowlist already permits), while Anthropic's backend reaches `/token`, `/register`, and the discovery documents through the tunnel.
## Setup component authentication failures
The [setup component](/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (Helm Job or Compose `setup` service) authenticates to the Tunnels API by exchanging an OIDC JWT through your federation rule. When the exchange fails, see [Troubleshoot a failed exchange](/docs/en/manage-claude/wif-reference#troubleshoot-a-failed-exchange) in the Workload Identity Federation reference; the failure modes (subject, audience, issuer, JWKS, lifetime) are the same.
Tunnels-specific causes:
- The chart's default audience is `api.anthropic.com` (no scheme). If your rule's audience is `https://api.anthropic.com`, set `api.wif.audience` to match.
- A `403` from the Tunnels API after a successful exchange means the rule's scope doesn't include `workspace:manage_tunnels`, or the rule's service account isn't a member of the tunnel's workspace. Set the scope and add the service account to the workspace.
On Helm, the setup component runs as a pre-install hook Job. On failure, the Job is left behind for inspection (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). Helm doesn't manage hook resources, so delete it before retrying:
```python
helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup
```
## Tunnel won't connect
Check the cloudflared logs first. Common causes:
- The `TUNNEL_TOKEN` is missing, expired, or copied incorrectly.
- A firewall is blocking outbound TCP/UDP on port 7844 to the tunnel edge.
cloudflared may also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
## Certificate errors
When Anthropic rejects the proxy's certificate during inner TLS, the proxy logs `tls handshake failed`. Verify that:
- The server certificate has not expired.
- The certificate's Subject Alternative Name matches `*.<tunnel-domain>`.
- The signing CA is registered with Anthropic for this tunnel.
See the [certificate requirements](/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements) for the full validation rules.
## Upstream IP validation
For SSRF protection, the proxy only dials addresses in the RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) by default. Only IPv4 is supported for the proxy-to-upstream connection. (The cloudflared-to-edge egress range in [Network requirements](/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements) is a different hop.)
If the proxy logs `IP validation failed: <ip> is not a private address`, the upstream hostname resolved outside that set. On Kubernetes, some managed distributions allocate the Service CIDR outside RFC1918; if `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` returns an address outside the private ranges, look up your cluster's Service CIDR and add it.
If the address is legitimate, add the narrowest covering CIDR to `upstream.allowed_ips`. Setting `allowed_ips` **replaces** the RFC1918 default rather than extending it, so include the private ranges your other upstream MCP servers use:
config/mcp-proxy.yaml
```python
upstream:
allowed_ips:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- 127.0.0.0/8 # loopback, for local testing only
```
Avoid `0.0.0.0/0` outside of local testing; it disables SSRF protection entirely.
---
## Agents-Tools/agents-and-tools-remote-mcp-servers-42aeab377e.md
# Remote MCP servers
---
Several companies have deployed remote MCP servers that developers can connect to via the Anthropic MCP connector API. These servers expand the capabilities available to developers and end users by providing remote access to various services and tools through the MCP protocol.
<Note>
The remote MCP servers listed below are third-party services designed to work with the Claude API. These servers
are not owned, operated, or endorsed by Anthropic. Users should only connect to remote MCP servers they trust and
should review each server's security practices and terms before connecting.
</Note>
## Connecting to remote MCP servers
To connect to a remote MCP server:
1. Review the documentation for the specific server you want to use.
2. Ensure you have the necessary authentication credentials.
3. Follow the server-specific connection instructions provided by each company.
For more information about using remote MCP servers with the Claude API, see the [MCP connector docs](/docs/en/agents-and-tools/mcp-connector).
## Remote MCP server examples
<MCPServersTable platform="mcpConnector" />
<Note>
**Looking for more?** [Find hundreds more MCP servers on GitHub](https://github.com/modelcontextprotocol/servers).
</Note>
---
## Agents-Tools/agents-and-tools-remote-mcp-servers-46c1f8e80f.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fremote-mcp-servers)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)MCP
# Remote MCP servers
Copy page
Connect Claude to third-party remote MCP servers through the MCP connector API. Browse example servers and review the steps to connect.
Copy page
Several companies have deployed remote MCP servers that developers can connect to by using the Anthropic MCP connector API. These servers expand the capabilities available to developers and end users by providing remote access to various services and tools through the MCP protocol.
The remote MCP servers listed below are third-party services designed to work with the Claude API. These servers are not owned, operated, or endorsed by Anthropic. Users should only connect to remote MCP servers they trust and should review each server's security practices and terms before connecting.
## Connecting to remote MCP servers
To connect to a remote MCP server:
1. Review the documentation for the specific server you want to use.
2. Ensure you have the necessary authentication credentials.
3. Follow the server-specific connection instructions provided by each company.
For more information about using remote MCP servers with the Claude API, see [MCP connector](/docs/en/agents-and-tools/mcp-connector).
Once connected, remote MCP tools follow the same triggering behavior as any other tool. See [When Claude uses MCP tools](/docs/en/agents-and-tools/mcp-connector#when-claude-uses-mcp-tools).
## Remote MCP server examples
[Ticket Tailor(opens in new tab)](https://help.tickettailor.com/en/articles/11892797-how-to-connect-ticket-tailor-to-your-favourite-ai-agent)
Event platform for managing tickets, orders & more
URL
``` inline-block
https://mcp.tickettailor.ai/mcp
```
[Linear(opens in new tab)](https://linear.app/docs/mcp)
Manage issues, projects & team workflows in Linear
URL
``` inline-block
https://mcp.linear.app/mcp
```
[Hugging Face(opens in new tab)](https://huggingface.co/settings/mcp)
Access the Hugging Face Hub and thousands of Gradio Apps
URL
``` inline-block
https://huggingface.co/mcp?login&gradio=none
```
[Blockscout(opens in new tab)](https://github.com/blockscout/mcp-server)
Access and analyze blockchain data
URL
``` inline-block
https://mcp.blockscout.com/mcp
```
[Close(opens in new tab)](https://help.close.com/v1/docs/en/mcp-server)
Connect Claude to Close CRM to securely access and act on your sales data
URL
``` inline-block
https://mcp.close.com/mcp
```
[Cloudflare Developer Platform(opens in new tab)](https://www.support.cloudflare.com/)
Build applications with compute, storage, and AI
URL
``` inline-block
https://bindings.mcp.cloudflare.com/mcp
```
[Egnyte(opens in new tab)](https://developers.egnyte.com/docs/Remote_MCP_Server)
Securely access and analyze Egnyte content
URL
``` inline-block
https://mcp-server.egnyte.com/mcp
```
[Figma(opens in new tab)](https://help.figma.com/hc/en-us/articles/32132100833559)
Generate diagrams and better code from Figma context
URL
``` inline-block
https://mcp.figma.com/mcp
```
[Guru(opens in new tab)](https://help.getguru.com/docs/connecting-gurus-mcp-server)
Search and interact with your company knowledge
URL
``` inline-block
https://mcp.api.getguru.com/mcp
```
[Jotform(opens in new tab)](https://www.jotform.com/developers/mcp/)
Create forms & analyze submissions inside Claude
URL
``` inline-block
https://mcp.jotform.com/mcp-app
```
[monday.com(opens in new tab)](https://developer.monday.com/apps/docs/mondaycom-mcp-integration)
Manage projects, boards, and workflows in monday.com
URL
``` inline-block
https://mcp.monday.com/mcp
```
[Notion(opens in new tab)](https://developers.notion.com/docs/mcp)
Connect your Notion workspace to search, update, and power workflows across tools
URL
``` inline-block
https://mcp.notion.com/mcp
```
[PayPal(opens in new tab)](https://mcp.paypal.com/)
Access PayPal payments platform
URL
``` inline-block
https://mcp.paypal.com/mcp
```
[Stripe(opens in new tab)](https://docs.stripe.com/mcp)
Payment processing and financial infrastructure tools
URL
``` inline-block
https://mcp.stripe.com
```
[Supabase(opens in new tab)](https://supabase.com/docs/guides/getting-started/mcp)
Manage databases, authentication, and storage
URL
``` inline-block
https://mcp.supabase.com/mcp
```
[Vercel(opens in new tab)](https://vercel.com/docs/mcp/vercel-mcp)
Analyze, debug, and manage projects and deployments
URL
``` inline-block
https://mcp.vercel.com/
```
[Wix(opens in new tab)](https://dev.wix.com/docs/sdk/articles/use-the-wix-mcp/about-the-wix-mcp)
Manage and build sites and apps on Wix
URL
``` inline-block
https://mcp.wix.com/mcp
```
[Coupler.io(opens in new tab)](https://help.coupler.io/article/592-coupler-local-mcp-server)
Access business data from hundreds of sources
URL
``` inline-block
https://mcp.coupler.io/mcp/
```
[Dice(opens in new tab)](https://www.dice.com/about/mcp)
Find active tech jobs on Dice
URL
``` inline-block
https://mcp.dice.com/mcp
```
[Miro(opens in new tab)](https://developers.miro.com/docs/miro-mcp)
Access and create new content on Miro boards
URL
``` inline-block
https://mcp.miro.com/
```
[Port IO(opens in new tab)](https://docs.port.io/ai-interfaces/port-mcp-server/overview-and-installation)
Search your context lake and safely run actions
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.port.io/ai-interfaces/port-mcp-server/overview-and-installation/?mcp-setup=claude®ion=eu#installing-port-mcp)
[Aiwyn Tax (formerly Column Tax)(opens in new tab)](https://docs.columntax.com/page/aiwyn-tax-mcp-server)
Estimate your federal & state taxes with Aiwyn's tax engine
URL
``` inline-block
https://mcp.columnapi.com/mcp
```
[Circleback(opens in new tab)](https://circleback.ai/docs/mcp)
Search and access context from meetings
URL
``` inline-block
https://app.circleback.ai/api/mcp
```
[Clarify(opens in new tab)](https://docs.clarify.ai/en/articles/13367278-clarify-mcp)
Query your CRM. Create records. Ask anything.
URL
``` inline-block
https://api.clarify.ai/mcp
```
[Clarity AI(opens in new tab)](https://clarity-sfdr20-mcp.pro.clarity.ai/)
Simulate fund classifications under proposed SFDR 2.0
URL
``` inline-block
https://clarity-sfdr20-mcp.pro.clarity.ai/mcp
```
[Day AI(opens in new tab)](https://day.ai/mcp)
Know everything about your prospects & customers with CRMx
URL
``` inline-block
https://day.ai/api/mcp
```
[ICD-10 Codes(opens in new tab)](https://claude.com/resources/tutorials/using-the-icd-10-connector-in-claude)
Access ICD-10-CM and ICD-10-PCS code sets
URL
``` inline-block
https://hcls.mcp.claude.com/icd10_codes/mcp
```
[DevRev(opens in new tab)](https://support.devrev.ai/en-US/devrev/article/ART-21859-remote-mcp-server)
Search and update your company's knowledge graph
URL
``` inline-block
https://api.devrev.ai/mcp/v1
```
[DirectBooker(opens in new tab)](https://www.directbooker.ai/products/mcp-server-documentation)
Compare hotels, then book direct
URL
``` inline-block
https://www.directbooker.ai/claude
```
[Exa(opens in new tab)](https://docs.exa.ai/reference/exa-mcp)
Web Search + Code Docs Search
URL
``` inline-block
https://mcp.exa.ai/mcp
```
[Fathom(opens in new tab)](https://help.fathom.video/en/articles/11497793)
Your meetings, now part of every Claude conversation
URL
``` inline-block
https://api.fathom.ai/mcp
```
[Fireflies(opens in new tab)](https://guide.fireflies.ai/articles/8272956938-learn-about-the-fireflies-mcp-server-model-context-protocol)
Analyze and generate insights from meeting transcripts
URL
``` inline-block
https://api.fireflies.ai/mcp
```
[Fiscal.ai(opens in new tab)](https://docs.fiscal.ai/docs/guides/mcp-integration)
Clean Public Equity Fundamental Data
URL
``` inline-block
https://api.fiscal.ai/mcp/sse
```
[Granola(opens in new tab)](https://help.granola.ai/article/granola-mcp#set-up-guide)
The AI notepad for meetings
URL
``` inline-block
https://mcp.granola.ai/mcp
```
[Harmonic(opens in new tab)](https://support.harmonic.ai/en/articles/12785899-harmonic-mcp-server-getting-started-guide)
Discover, research, and enrich companies and people
URL
``` inline-block
https://mcp.api.harmonic.ai
```
[Klarity(opens in new tab)](https://github.com/Klarity-AI/klarity-mcp/blob/main/skills/klarity-process-context-graph/SKILL.md)
Explore your org's processes
URL
``` inline-block
https://architect-v2-api.klarity.ai/mcp
```
[Krisp(opens in new tab)](https://help.krisp.ai/hc/en-us/articles/25416265429660-Krisp-MCP-Supported-tools)
Add your meetings context via transcripts and notes
URL
``` inline-block
https://mcp.krisp.ai/mcp
```
[Lawve AI(opens in new tab)](https://lawve.ai/en/learn/mcp-setup)
Discover expert-written skills for legal work
URL
``` inline-block
https://mcp.lawve.ai/mcp
```
[Lorikeet(opens in new tab)](https://docs.lorikeetcx.ai/mcp/mcp-server)
A universal concierge for complex businesses
URL
``` inline-block
https://mcp.lorikeetcx.ai
```
[LunarCrush(opens in new tab)](https://lunarcrush.com/developers/api/ai)
Add real-time social media data to your searches
URL
``` inline-block
https://lunarcrush.ai/mcp
```
[Mem(opens in new tab)](https://docs.mem.ai/mcp/overview)
The AI notebook for everything on your mind
URL
``` inline-block
https://mcp.mem.ai/mcp
```
[Metaview(opens in new tab)](https://support.metaview.ai/integrations/mcp-integration/mcp-overview.mdx)
The AI platform for recruiting.
URL
``` inline-block
https://mcp.metaview.ai/mcp
```
[Otter.ai(opens in new tab)](https://help.otter.ai/hc/en-us/articles/35287607569687-Otter-MCP-Server)
Unlock your meeting intelligence
URL
``` inline-block
https://mcp.otter.ai/mcp
```
[Peec AI(opens in new tab)](https://docs.peec.ai/mcp/introduction)
Analyze your brand's visibility across LLMs
URL
``` inline-block
https://api.peec.ai/mcp
```
[Read AI(opens in new tab)](https://support.read.ai/hc/en-us/articles/49381158409491-MCP-Server)
Bring your meetings into Claude
URL
``` inline-block
https://api.read.ai/mcp
```
[Scholar Gateway(opens in new tab)](https://docs.scholargateway.ai)
Enhance responses with scholarly research and citations
URL
``` inline-block
https://connector.scholargateway.ai/mcp
```
[Scite(opens in new tab)](https://scite.ai/mcp)
Evidence-based answers grounded in research
URL
``` inline-block
https://api.scite.ai/mcp
```
[Sprouts Data Intelligence(opens in new tab)](https://support.sprouts.ai/en/articles/13384582-sprouts-mcp-server-documentation#h_541c149a52)
From query to qualified lead in seconds.
URL
``` inline-block
https://sprouts-mcp-server.kartikay-dhar.workers.dev
```
[Sybill(opens in new tab)](https://api.sybill.ai/docs/mcp.html)
Ask AI about your sales calls, deals & pipeline
URL
``` inline-block
https://mcp.sybill.ai/mcp
```
[Tray.ai(opens in new tab)](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
Automate 700+ apps & workflows with governance
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
[Vibe Prospecting(opens in new tab)](https://developers.explorium.ai/mcp-docs/agentsource-mcp)
Find company & contact data
URL
``` inline-block
https://vibeprospecting.explorium.ai/mcp
```
[Windsor.ai(opens in new tab)](https://windsor.ai/introducing-windsor-mcp/#method-1-using-claude-desktop-3)
Connect Meta Ads, Google Ads, TikTok Ads, LinkedIn Ads + 320 more
URL
``` inline-block
https://mcp.windsor.ai
```
[Era Context(opens in new tab)](https://era.app/help/mcp-server-era-context/)
Manage your personal finances using Claude
URL
``` inline-block
https://context.era.app
```
[Fellow.ai(opens in new tab)](https://help.fellow.ai/en/articles/12622641-fellow-s-mcp-server)
Chat with your meetings to uncover actionable insights
URL
``` inline-block
https://fellow.app/mcp
```
[Gamma(opens in new tab)](https://gamma.app/docs/Gamma-MCP-Server-Documentation-m6p43kobgzy15zj?mode=doc)
Create presentations, docs, socials, and sites with AI
URL
``` inline-block
https://mcp.gamma.app/mcp
```
[Lucid(opens in new tab)](https://help.lucid.co/hc/en-us/articles/42578801807508-Integrate-Lucid-with-AI-tools-using-the-Lucid-MCP-server)
Ideate, diagram, and align teams
URL
``` inline-block
https://mcp.lucid.app/mcp
```
[Natoma(opens in new tab)](https://docs.natoma.ai)
Access all your internal tools, enterprise apps & data.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://natoma.app/?utm=claude)
[NetDocuments(opens in new tab)](https://support.netdocuments.com/)
Securely access your documents in NetDocuments
[Netlify(opens in new tab)](https://docs.netlify.com/build/build-with-ai/netlify-mcp-server/)
Create, deploy, manage, and secure websites on Netlify.
URL
``` inline-block
https://netlify-mcp.netlify.app/mcp
```
[ThoughtSpot Spotter(opens in new tab)](https://developers.thoughtspot.com/docs/mcp-integration#_add_mcp_server_to_the_mcp_clients_config)
Your AI data analyst, from question to trusted insights
URL
``` inline-block
https://agent.thoughtspot.app/mcp?api-version=latest
```
[AWS Marketplace(opens in new tab)](https://docs.aws.amazon.com/marketplace/latest/APIReference/marketplace-mcp-server.html)
Discover, evaluate, and buy solutions for the cloud
URL
``` inline-block
https://marketplace-mcp.us-east-1.api.aws/mcp
```
[Synthesize Bio(opens in new tab)](https://app.synthesize.bio/mcp/docs)
Generate gene expression from a virtual human
URL
``` inline-block
https://app.synthesize.bio/api/mcp
```
[Kindora Funder Discovery(opens in new tab)](https://kindora.co/mcp)
Find funders who support causes like yours
URL
``` inline-block
https://kindora-mcp.azurewebsites.net/mcp/
```
[Omni Analytics(opens in new tab)](https://docs.omni.co/ai/mcp)
Query your data using natural language through Omni's semantic model
URL
``` inline-block
https://callbacks.omniapp.co/callback/mcp
```
[Send(opens in new tab)](https://www.send.co/mcp/docs)
Create shareable documents, one-pagers, and decks
URL
``` inline-block
https://www.send.co/mcp
```
[Shapes(opens in new tab)](https://mcp.shapes.co)
Analyse your live people data, right in Claude
URL
``` inline-block
https://mcp.shapes.co/mcp
```
[Lloyd by The L Suite(opens in new tab)](https://docs.google.com/document/d/1glRh-BdxnTPxzM1cZLzCcmlgIW5-dQ4-NnnStfhI6vk/edit?tab=t.0#heading=h.hgwkvyizzdb3)
Inhouse counsel insights for members of The L Suite
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.google.com/forms/d/e/1FAIpQLSeK2KFt1G1XbqgQdp2J-cvnLDtiUDigSsTjFH-Hk_B-Va0pRw/viewform?usp=publish-editor)
[TopCounsel by The L Suite(opens in new tab)](https://docs.google.com/document/d/1jcekau3Njlc5XfSspSdSGu7qSgKvM00M6DrYm91ZTzA/edit?tab=t.0#heading=h.hgwkvyizzdb3)
Outside Counsel recommendations from Inhouse Counsel
URL
``` inline-block
https://api.techgc.co/api/mcp/topcounsel
```
[ActiveCampaign(opens in new tab)](https://developers.activecampaign.com/page/mcp)
Autonomous marketing to transform how you work
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://developers.activecampaign.com/page/mcp)
[Adobe Experience Manager(opens in new tab)](https://www.adobe.com/go/aem_claude_mcp_docs)
Manage your Adobe Experience Manager content
URL
``` inline-block
https://mcp.adobeaemcloud.com/adobe/mcp/aem
```
[Ahrefs(opens in new tab)](https://docs.ahrefs.com/docs/mcp/reference/introduction)
SEO & AI search analytics
URL
``` inline-block
https://api.ahrefs.com/mcp/mcp
```
[AirOps(opens in new tab)](https://docs.airops.com/mcp)
Craft content that wins AI search
URL
``` inline-block
https://app.airops.com/mcp
```
[Airtable(opens in new tab)](https://support.airtable.com/docs/using-the-airtable-mcp-server)
Bring your structured data to Claude
URL
``` inline-block
https://mcp.airtable.com/mcp
```
[Airwallex Developer(opens in new tab)](https://www.airwallex.com/docs/developer-tools/ai/developer-mcp)
Integrate with the Airwallex Platform using Claude
URL
``` inline-block
https://mcp-demo.airwallex.com/developer
```
[AllTrails(opens in new tab)](https://support.alltrails.com/hc/en-us/articles/47343827423764-AllTrails-integrations-with-AI-services)
Find your next hike
URL
``` inline-block
https://www.alltrails.com/mcp
```
[Attio(opens in new tab)](https://docs.attio.com/mcp/overview)
Search, manage, and update your Attio CRM from Claude
URL
``` inline-block
https://mcp.attio.com/mcp
```
[Audible(opens in new tab)](https://help.audible.com/s/article/connect-audible-to-claude?language=en_US)
Ask for audiobook recommendations
URL
``` inline-block
https://mcp.audible.com/mcp
```
[Autodesk Product Help(opens in new tab)](https://help.autodesk.com/view/ADSKMCP/ENU/?guid=ADSKMCP_KnowledgeMcp_autodesk_product_help_mcp_server_html)
Securely access Autodesk's help documentation
URL
``` inline-block
https://developer.api.autodesk.com/knowledge/public/v1/mcp
```
[Base44(opens in new tab)](https://docs.base44.com/developers/backend/overview/mcp-server)
Build and manage Base44 apps
URL
``` inline-block
https://app.base44.com/mcp
```
[Benchling(opens in new tab)](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
Connect to R&D data, source experiments, and notebooks
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
[BioRender(opens in new tab)](https://help.biorender.com/hc/en-gb/articles/30870978672157-How-to-use-the-BioRender-MCP-connector)
Search for and use scientific templates and icons
URL
``` inline-block
https://mcp.services.biorender.com/mcp
```
[Bitly(opens in new tab)](https://dev.bitly.com/bitly-mcp/)
Shorten links, generate QR Codes, and track performance
URL
``` inline-block
https://api-ssl.bitly.com/v4/mcp
```
[MT Newswires(opens in new tab)](https://console.blueskyapi.com/docs/EDGE/news/MT_NEWSWIRES_Global#mcp)
Trusted real-time global financial news provider
URL
``` inline-block
https://vast-mcp.blueskyapi.com/mcp
```
[Booking.com(opens in new tab)](https://developers.booking.com/mcp/booking-connector/about)
Find hotels, homes and more
URL
``` inline-block
https://demandapi-mcp.booking.com/v1/mcp/8132308
```
[Box(opens in new tab)](https://developer.box.com/guides/box-mcp)
Search, edit and get insights on your Box content
URL
``` inline-block
https://mcp.box.com
```
[Brex(opens in new tab)](https://www.brex.com/support/using-brex-in-ai-apps)
Intelligent finance automation
URL
``` inline-block
https://api.brex.com/mcp
```
[Orion by Gravity(opens in new tab)](http://docs.runorion.com/)
Get insights from your autonomous AI analyst
URL
``` inline-block
https://g.runorion.com/mcp
```
[Calendly(opens in new tab)](https://help.calendly.com/hc/en-us/articles/36734570264855-Connect-Calendly-to-your-AI-tools-with-Calendly-MCP)
Manage event types, availability, and bookings.
URL
``` inline-block
https://mcp.calendly.com
```
[Canva(opens in new tab)](https://www.canva.dev/docs/connect/canva-mcp-server-setup/)
Search, create, autofill, and export Canva designs
URL
``` inline-block
https://mcp.canva.com/mcp
```
[Carta(opens in new tab)](https://docs.carta.com/api-platform/docs/claude-plugins-setup)
The connected ERP for private capital
URL
``` inline-block
https://mcp.app.carta.com/mcp
```
[CB Insights(opens in new tab)](https://mcp.cbinsights.com)
Predictive intelligence on private companies
URL
``` inline-block
https://mcp.cbinsights.com
```
[CData Connect AI(opens in new tab)](https://cloud.cdata.com/docs/Claude-Client.html)
Managed MCP platform for 350 sources
URL
``` inline-block
https://mcp.cloud.cdata.com/mcp
```
[Microsoft 365(opens in new tab)](https://support.claude.com/en/articles/12542951-enabling-and-using-the-microsoft-365-connector)
Access your company's SharePoint, OneDrive, Outlook, and Teams directly in Claude
URL
``` inline-block
https://microsoft365.mcp.claude.com/mcp
```
[PubMed(opens in new tab)](https://support.claude.com/en/)
Search biomedical literature from PubMed
URL
``` inline-block
https://pubmed.mcp.claude.com/mcp
```
[Clay(opens in new tab)](https://www.notion.so/clayrun/Clay-Claude-MCP-Server-Documentation-2ef7e66eb01480c9820de48041591aeb?showMoveTo=true&saveParent=true)
Find prospects. Research accounts. Personalize outreach
URL
``` inline-block
https://api.clay.com/v3/mcp
```
[Clerk(opens in new tab)](https://clerk.com/docs/guides/ai/mcp/clerk-mcp-server)
Add authentication, organizations, and billing
URL
``` inline-block
https://mcp.clerk.com/mcp
```
[ClickUp(opens in new tab)](https://help.clickup.com/hc/en-us/articles/33335772678423-What-is-ClickUp-MCP)
Project management & collaboration for teams & agents
URL
``` inline-block
https://mcp.clickup.com/mcp
```
[iManage Work(opens in new tab)](https://docs.imanage.com/cloud/mcpconnector-user-help/en-US/iManage_MCP_Connector_Help.html)
Governed knowledge. AI ready.
URL
``` inline-block
https://cloudimanage.com/mcp/work
```
[Cloudinary(opens in new tab)](https://cloudinary.com/documentation/cloudinary_llm_mcp#available_mcp_servers)
Manage, transform and deliver your images & videos
URL
``` inline-block
https://asset-management.mcp.cloudinary.com/sse
```
[CoinDesk(opens in new tab)](https://mcp.coindesk.com/)
Access Live & Historical Crypto Data, Indices
URL
``` inline-block
https://mcp.coindesk.com/mcp
```
[Consensus(opens in new tab)](https://docs.consensus.app/docs/mcp)
Explore scientific research
URL
``` inline-block
https://mcp.consensus.app/mcp
```
[Aurora(opens in new tab)](https://mcp-docs.ai.consilio.com)
Search your Consilio matters, docs, and more.
URL
``` inline-block
https://mcp.ai.consilio.com
```
[Contentsquare(opens in new tab)](https://support.contentsquare.com/hc/en-us/articles/41563169756945-Model-Context-Protocol-MCP)
Experience analytics platform for digital businesses
URL
``` inline-block
https://api.contentsquare.com/mcp
```
[Context7(opens in new tab)](https://context7.com/docs/overview)
Up-to-date docs for LLMs and AI code editors
URL
``` inline-block
https://mcp.context7.com/mcp
```
[CourtListener(opens in new tab)](https://github.com/freelawproject/courtlistener-api-client/blob/main/MCP_README.md)
Legal research across millions of court records
URL
``` inline-block
https://mcp.courtlistener.com/
```
[Courtroom5(opens in new tab)](https://courtroom5.com/claude)
Civil legal guidance for self-represented litigants
URL
``` inline-block
https://mcp.courtroom5.com/v1
```
[Intuit Credit Karma(opens in new tab)](https://support.creditkarma.com/s/article/Intuit-Credit-Karma-on-Claude-and-ChatGPT)
Credit score factors & insights
URL
``` inline-block
https://anthropic.mcp.creditkarma.com/mcp
```
[Crossbeam(opens in new tab)](https://help.crossbeam.com/en/articles/12601327-crossbeam-mcp-server-beta)
Explore partner data and ecosystem insights in Claude
URL
``` inline-block
https://mcp.crossbeam.com
```
[Crypto.com(opens in new tab)](https://mcp.crypto.com/docs)
Real time prices, orders, charts, and more for crypto
URL
``` inline-block
https://mcp.crypto.com/market-data/mcp
```
[Daloopa(opens in new tab)](https://docs.daloopa.com/docs/daloopa-mcp#/)
Financial fundamental data and KPIs with hyperlinks
URL
``` inline-block
https://mcp.daloopa.com/server/mcp
```
[Databricks(opens in new tab)](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
Managed MCP servers with Unity Catalog and Mosaic AI
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
[Datadog(opens in new tab)](https://docs.datadoghq.com/bits_ai/mcp_server/)
Debug and resolve issues using Datadog telemetry
[Datasite(opens in new tab)](https://app.global.datasite.com/dev-portal/guides/mcp-server)
Manage your M&A data room from Claude
URL
``` inline-block
https://mcp.global.datasite.com/mcp
```
[Definely(opens in new tab)](https://help.definely.com/en/articles/634922-definely-connector-for-claude-user-guide)
Structured contract review tools for legal teams
URL
``` inline-block
https://mcp.app.definely.com
```
[Descript(opens in new tab)](https://help.descript.com/hc/en-us/articles/45008080343053-Connect-Descript-to-Claude)
Import, edit, or create video with prompts
URL
``` inline-block
https://api.descript.com/v2/mcp/claude
```
[Descrybe Legal Engine(opens in new tab)](https://app.descrybe.com/connect/docs)
Ground your work in clean, structured U.S. primary law
URL
``` inline-block
https://mcp.descrybe.com/mcp
```
[Digits(opens in new tab)](https://help.digits.com/business-connections/digits-mcp-claude)
Track and analyze your finances with Digits
URL
``` inline-block
https://api.digits.com/mcp
```
[D&B Risk Analytics(opens in new tab)](https://view.highspot.com/viewer/2b3c0624606b4d64eb092106b47ad14c)
Execute risk workflows powered by the D&B Commercial Graph™
URL
``` inline-block
https://agents.riskanalytics.dnb.com/mcp
```
[DocuSeal(opens in new tab)](https://www.docuseal.com/guides/integrate-with-ai-agents-using-mcp)
Sign, send & manage documents with DocuSeal
URL
``` inline-block
https://docuseal.com/mcp
```
[Dovetail(opens in new tab)](https://developers.dovetail.com/docs/mcp)
Turn scattered feedback into decisions grounded in customer evidence
URL
``` inline-block
https://dovetail.com/api/mcp
```
[Dremio Cloud(opens in new tab)](https://docs.dremio.com/cloud/sonar/mcp-server/)
Analyze and get insights from your lakehouse data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.dremio.com/cloud/sonar/mcp-server/)
[Enterpret(opens in new tab)](https://helpcenter.enterpret.com/en/articles/12665166-wisdom-mcp-server)
Get answers from unified feedback of your customers.
URL
``` inline-block
https://wisdom-api.enterpret.com/server/mcp
```
[Euler(opens in new tab)](https://mcp.eulerapp.com/public/docs)
Chat and manage your entire partner program.
URL
``` inline-block
https://mcp.eulerapp.com/mcp
```
[Everlaw(opens in new tab)](https://support.everlaw.com/hc/en-us/articles/50274473477915)
Search and explore your Everlaw database in Claude.
URL
``` inline-block
https://api.everlaw.com/v1/mcp
```
[Expedia(opens in new tab)](https://www.expedia.com/playground/mcp/doc/)
Plan trips, flights and hotels
URL
``` inline-block
https://www.expedia.com/mcp
```
[Fever Event Discovery(opens in new tab)](https://developer.feverup.com/)
Discover live entertainment events worldwide
URL
``` inline-block
https://data-search.apigw.feverup.com/mcp
```
[FMP(opens in new tab)](https://financialmodelingprep.com/developer/docs/mcp-server?utm_source=claude)
Comprehensive financial market data
URL
``` inline-block
https://financialmodelingprep.com/mcp
```
[G2(opens in new tab)](https://documentation.g2.com/docs/g2-mcp-server)
Bring real buyer signals into AI workflows
URL
``` inline-block
https://mcp.g2.com/mcp
```
[Monte Carlo(opens in new tab)](https://docs.getmontecarlo.com/docs/mcp-server)
Data & AI observability
URL
``` inline-block
https://mcp.getmontecarlo.com/mcp
```
[Glean(opens in new tab)](https://docs.glean.com/administration/platform/mcp/about)
Bring enterprise context to Claude and your AI tools
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.glean.com/administration/platform/mcp/about)
[Glovo(opens in new tab)](https://glovoapp.com/docs/en/legal/mcp/)
Anything delivered in minutes
URL
``` inline-block
https://api.glovoapp.com/discovery-mcp/mcp
```
[GoCardless(opens in new tab)](https://developer.gocardless.com/developer-tools/mcp/)
Build GoCardless payment API integrations
URL
``` inline-block
https://mcp.gocardless.com
```
[GoDaddy(opens in new tab)](https://developer.godaddy.com/mcp)
Search domains and check availability
URL
``` inline-block
https://api.godaddy.com/v1/domains/mcp
```
[Goodnotes(opens in new tab)](https://www.notion.so/goodnotes-team/Goodnotes-MCP-Server-Documentation-320b740273d28187a23ad52780a37620)
Turn AI insights into documents
URL
``` inline-block
https://claude-mcp-api.ml.goodnotes.com/mcp
```
[Google Cloud BigQuery(opens in new tab)](https://cloud.google.com/bigquery/docs/use-bigquery-mcp)
BigQuery: Advanced analytical insights for agents
URL
``` inline-block
https://bigquery.googleapis.com/mcp
```
[Google Compute Engine(opens in new tab)](https://cloud.google.com/docs)
MCP server for Google Compute Engine
URL
``` inline-block
https://compute.googleapis.com/mcp
```
[Google Calendar(opens in new tab)](https://developers.google.com/workspace/calendar)
Manage your schedule and coordinate meetings effortlessly
URL
``` inline-block
https://calendarmcp.googleapis.com/mcp/v1
```
[Google Drive(opens in new tab)](https://developers.google.com/workspace/drive)
Search, read, and upload files instantly
URL
``` inline-block
https://drivemcp.googleapis.com/mcp/v1
```
[Gmail(opens in new tab)](https://developers.google.com/workspace/gmail)
Draft replies, summarize threads, & search your inbox
URL
``` inline-block
https://gmailmcp.googleapis.com/mcp/v1
```
[GovTribe(opens in new tab)](https://docs.govtribe.com/user-guide/integrations/govtribe-mcp)
Search government procurement & spending data
URL
``` inline-block
https://govtribe.com/mcp
```
[Grain(opens in new tab)](https://developers.grain.com/mcp)
Put your meetings to work
URL
``` inline-block
https://api.grain.com/_/mcp
```
[Granted(opens in new tab)](https://grantedai.com/mcp)
Discover every grant opportunity in existence.
URL
``` inline-block
https://grantedai.com/api/mcp/mcp
```
[Guidepoint(opens in new tab)](https://clapi-developer.guidepoint.io/mcp/docs)
Real-time access to trusted expert knowledge
URL
``` inline-block
https://clapi.guidepoint.io/mcp-server/v1/mcp
```
[Gusto(opens in new tab)](https://docs.gusto.com/app-integrations/docs/mcp)
Query and analyze your Gusto data
URL
``` inline-block
https://mcp.api.gusto.com/anthropic
```
[Phoenix by HG Insights(opens in new tab)](https://phoenix.hginsights.com/docs/intro)
AI-powered B2B data intelligence & analytics
URL
``` inline-block
https://phoenix.hginsights.com/api/ai/mcp
```
[HubSpot(opens in new tab)](https://knowledge.hubspot.com/integrations/set-up-and-use-the-hubspot-connector-for-claude)
Chat with your CRM data to get personalized insights
URL
``` inline-block
https://mcp.hubspot.com/anthropic
```
[IBISWorld(opens in new tab)](https://help.ibisworld.com/en/articles/14627556-ibisworld-mcp-server-documentation)
Financials, risk data and analysis on 50,000 industries
URL
``` inline-block
https://mcp.ibisworld.com
```
[Interactive Brokers (IBKR)(opens in new tab)](https://www.interactivebrokers.com/lib/cstools/faq/#/content/1442566213)
Trade, invest, analyze, and manage global markets
URL
``` inline-block
https://api.ibkr.com/v1/api/mcp
```
[ICE Data Services(opens in new tab)](https://www.ice.com/ieoauoau)
Analyze U.S. fixed income trade and reference data
URL
``` inline-block
https://fids-mcp.ice.com/mcp
```
[IFTTT(opens in new tab)](https://ift.tt/ai_assistants)
Connect, control, and automate 1,000+ apps with IFTTT
URL
``` inline-block
https://ifttt.com/mcp
```
[Medidata(opens in new tab)](https://learn.medidata.com/en-US/bundle/mcp-server-documentation/page/medidata_mcp_server_documentation.html)
Clinical trial software and site ranking tools
URL
``` inline-block
https://mcp.imedidata.com/mcp
```
[Indeed(opens in new tab)](https://docs.indeed.com/mcp)
Search for jobs on Indeed
URL
``` inline-block
https://mcp.indeed.com/claude/mcp
```
[Instacart(opens in new tab)](https://docs.instacart.com/mcp_servers/)
Groceries and more delivered as fast as 30 minutes
URL
``` inline-block
https://fig-mcp.instacart.com/mcp
```
[Intercom(opens in new tab)](https://developers.intercom.com/docs/guides/mcp)
Access to Intercom data for better customer insights
URL
``` inline-block
https://mcp.intercom.com/mcp
```
[Intuit Mailchimp(opens in new tab)](https://mailchimp.com/help/use-mailchimp-connector-claude)
Create marketing campaigns
URL
``` inline-block
https://ai-inc.mailchimp.com/claude/mcp/v2
```
[Intuit QuickBooks(opens in new tab)](https://quickbooks.intuit.com/learn-support/en-us/help-article/accounting-bookkeeping/use-quickbooks-connector-claude/L3YBlo6Ht_US_en_US?uid=mmzgz9ag)
Business Finances made simple
URL
``` inline-block
https://ai-inc.quickbooks.intuit.com/v1/mcp
```
[Intuit TurboTax(opens in new tab)](https://ttlc.intuit.com/turbotax-support/en-us/help-article/tax-return/access-turbotax-tools-claude)
Estimate tax refunds and connect with live tax experts
URL
``` inline-block
https://ai-inc.turbotax.intuit.com/358A1C1B-F73B-46A7-B130-4B14916E6843/v1/mcp
```
[Ironclad Contracts(opens in new tab)](https://support.ironcladapp.com/hc/en-us/articles/39887091143319-Ironclad-MCP-Server)
Plain language search for faster contract answers
[Jentic(opens in new tab)](https://docs.jentic.com/guides/mcp/remote-mcp/)
One connection to access all your tools securely
URL
``` inline-block
https://api.jentic.com/mcp
```
[PlayMCP(opens in new tab)](https://www.notion.so/2189b97b4888803dbbdcef264e7eff58)
Connect and use PlayMCP servers in your toolbox
URL
``` inline-block
https://playmcp.kakao.com/mcp
```
[S&P Global(opens in new tab)](https://docs.kensho.com/llmreadyapi/mcp)
Query a range of S&P Global datasets
URL
``` inline-block
https://kfinance.kensho.com/integrations/mcp
```
[Ketryx(opens in new tab)](https://docs.ketryx.com/reference/ketryx-mcp-server)
Search and explore regulated software lifecycle data
URL
``` inline-block
https://app.ketryx.com/api/mcp
```
[Kiwi.com(opens in new tab)](https://mcp-install-instructions.alpic.cloud/servers/kiwi-com-flight-search)
Search flights in Claude
URL
``` inline-block
https://mcp.kiwi.com
```
[Klaviyo(opens in new tab)](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server)
Report, strategize & create with real-time Klaviyo data
URL
``` inline-block
https://mcp.klaviyo.com/mcp?include-mcp-app=true
```
[lastminute.com(opens in new tab)](https://mcp.lastminute.com/docs)
Search, compare and book flights, dynamic packages (flight + hotel) and hotels across global airlines and hotel suppliers.
URL
``` inline-block
https://mcp.lastminute.com/mcp
```
[Legal Data Hunter(opens in new tab)](https://legaldatahunter.com/docs)
Search 23M+ legal docs in 160+ jurisdictions.
URL
``` inline-block
https://legaldatahunter.com/mcp
```
[LILT(opens in new tab)](https://support.lilt.com/kb/LILT-mcp)
High-quality translation with human verification
URL
``` inline-block
https://mcp.lilt.com/mcp
```
[Local Falcon(opens in new tab)](https://github.com/local-falcon/mcp)
AI visibility and local search intelligence platform
URL
``` inline-block
https://mcp.localfalcon.com
```
[LSEG(opens in new tab)](https://www.lseg.com/en/solutions/ai-finance-solutions/anthropic)
Access best in class data & analytics across a broad spectrum of asset classes.
URL
``` inline-block
https://api.analytics.lseg.com/lfa/mcp/server-cl
```
[Lumin(opens in new tab)](https://github.com/luminpdf/lumin-mcp-server)
Manage documents, send signature requests, and convert Markdown to PDF
URL
``` inline-block
https://mcp.luminpdf.com/mcp
```
[Lusha(opens in new tab)](https://docs.lusha.com/mcp-docs)
Find and enrich B2B contacts and companies
URL
``` inline-block
https://mcp.lusha.com/mcp/claude
```
[Magic Patterns(opens in new tab)](https://www.magicpatterns.com/docs/documentation/features/mcp-server/overview)
Discuss and iterate on Magic Patterns designs
URL
``` inline-block
https://mcp.magicpatterns.com/mcp
```
[MailerLite(opens in new tab)](https://developers.mailerlite.com/mcp/#how-mcp-works)
Turn Claude into your email marketing assistant
URL
``` inline-block
https://mcp.mailerlite.com/mcp
```
[Make(opens in new tab)](https://developers.make.com/mcp-server/)
Run Make scenarios and manage your Make account
URL
``` inline-block
https://mcp.make.com
```
[Malwarebytes(opens in new tab)](https://help.malwarebytes.com/hc/en-us/articles/47985341083675-Using-Malwarebytes-in-Claude)
Check links, phones, and emails for scams
URL
``` inline-block
https://scamguard.malwarebytes.com/claude/mcp
```
[Melon(opens in new tab)](https://tech.kakaoent.com/ai/using-melon-mcp-server-en/)
Browse music charts & your personalized music picks
URL
``` inline-block
https://mcp.melon.com/mcp/
```
[Mercury(opens in new tab)](https://docs.mercury.com/docs/connecting-mercury-mcp)
Search, analyze and understand your finances on Mercury
URL
``` inline-block
https://mcp.mercury.com/mcp
```
[Metabase(opens in new tab)](https://www.metabase.com/docs/latest/ai/mcp)
Query and explore your Metabase data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://www.metabase.com/docs/latest/ai/mcp)
[Microsoft Learn(opens in new tab)](https://learn.microsoft.com/en-us/training/support/mcp)
Search trusted Microsoft docs to power your development
URL
``` inline-block
https://learn.microsoft.com/api/mcp
```
[Mintlify(opens in new tab)](https://www.mintlify.com/docs/ai/mintlify-mcp)
Search, read, and edit your documentation
URL
``` inline-block
https://mcp.mintlify.com
```
[Mixpanel(opens in new tab)](https://docs.mixpanel.com/docs/features/mcp)
Analyze, query, and manage your Mixpanel data
URL
``` inline-block
https://mcp.mixpanel.com/mcp
```
[Moody's(opens in new tab)](https://www.moodys.com/web/en/us/genai/model-context-protocol.html)
Risk insights, analytics, and decision intelligence
URL
``` inline-block
https://api.moodys.com/genai-ready-data/m1/mcp
```
[Morningstar(opens in new tab)](https://developer.morningstar.com/direct-web-services/documentation/mcp-server/morningstar-mcp-server)
Up-to-date investment and market insights
URL
``` inline-block
https://mcp.morningstar.com/mcp
```
[MotherDuck(opens in new tab)](https://motherduck.com/docs/sql-reference/mcp/)
Get answers from your data
URL
``` inline-block
https://api.motherduck.com/mcp
```
[Motion Creative Analytics(opens in new tab)](https://help.motionapp.com/en/articles/14315735-motion-mcp)
Analyze your Meta ad creative & competitor ad libraries
URL
``` inline-block
https://projects.motionapp.com/mcp
```
[MSCI(opens in new tab)](https://www.msci.com/downloads/web/msci-com/data-and-analytics/private-asset-solutions/ai-for-private-markets/msci-mcp-msci-connector-user-guide.pdf)
Turn data into insight
URL
``` inline-block
https://mcp.msci.com/mcp/v1.0/mcp
```
[NetSuite(opens in new tab)](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7200233106.html)
Connect Claude to NetSuite data for analysis & insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://system.netsuite.com/mcp/mcpinfo.nl)
[Owkin(opens in new tab)](https://docs.owkin.com/core-features-and-usage)
Interact with AI agents built for biology
URL
``` inline-block
https://mcp.k.owkin.com/mcp
```
[PagerDuty(opens in new tab)](https://developer.pagerduty.com/docs/mcp-tooling-remote-server)
Manage incidents, services and on-call schedules
URL
``` inline-block
https://mcp.pagerduty.com/mcp
```
[PandaDoc(opens in new tab)](https://developers.pandadoc.com/docs/how-to-use-the-pandadoc-mcp-server)
Create, send, sign and track documents
URL
``` inline-block
https://mcp.pandadoc.com/v1/mcp
```
[Pigment(opens in new tab)](https://kb.pigment.com/docs/mcp-server)
Analyze business data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://kb.pigment.com/docs/mcp-server)
[PitchBook Premium(opens in new tab)](https://help.pitchbook.com/s/article/PitchBook-Premium-for-Claude-by-Anthropic)
PitchBook data, embedded in the way you work.
URL
``` inline-block
https://premium.mcp.pitchbook.com/mcp
```
[Polar Analytics(opens in new tab)](https://intercom.help/polar-app/en/collections/17268490-polar-mcp)
Bring all your data in one place & connect it to Claude
URL
``` inline-block
https://api.polaranalytics.com/mcp
```
[Postman(opens in new tab)](https://github.com/postmanlabs/postman-mcp-server)
Give API context to your coding agents
URL
``` inline-block
https://mcp.postman.com/minimal
```
[Privacy.com(opens in new tab)](https://developers.privacy.com/docs/mcp-server)
Manage virtual cards and track your spending patterns
URL
``` inline-block
https://mcp.privacy.com
```
[Quartr(opens in new tab)](https://mcp.quartr.com/docs)
Financial data and AI infrastructure for company research.
URL
``` inline-block
https://mcp.quartr.com/mcp
```
[Quo(opens in new tab)](https://support.quo.com/core-concepts/integrations/mcp)
Surface call insights and missed opportunities
URL
``` inline-block
https://mcp.quo.com/mcp
```
[Ramp(opens in new tab)](https://docs.ramp.com/developer-api/v1/guides/ramp-mcp-remote)
Search, access, and analyze your Ramp financial data
URL
``` inline-block
https://ramp-mcp-remote.ramp.com/mcp
```
[Ramp Data(opens in new tab)](https://docs.ramp.com/developer-api/v1/ramp-data)
Search and analyze Ramp spend across 50,000+ businesses
URL
``` inline-block
https://mcp.ramp.com/ramp-data/anthropic/mcp
```
[Bigdata.com(opens in new tab)](https://docs.bigdata.com/mcp-reference)
Access real-time financial data
URL
``` inline-block
https://mcp.bigdata.com/
```
[Razorpay(opens in new tab)](https://razorpay.com/docs/mcp-server/?preferred-country=IN)
Turn Claude into your Razorpay Dashboard Assistant
URL
``` inline-block
https://mcp.razorpay.com/mcp
```
[Resy(opens in new tab)](https://www.americanexpress.com/content/dam/amex/en-us/credit-cards/benefits/resy/resy_mcp_app_claude.pdf)
Find and book restaurants instantly
URL
``` inline-block
https://apigw.americanexpress.com/dining/v1/mcp
```
[Retool(opens in new tab)](https://docs.retool.com/education/labs/resources/mcp)
Build production apps and manage Retool with AI agents
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.retool.com/education/labs/resources/mcp)
[Rillet(opens in new tab)](https://docs.api.rillet.com/docs/mcp)
Query your live GL and financials in plain English
URL
``` inline-block
https://api.rillet.com/mcp
```
[SandboxAQ(opens in new tab)](https://docs.aisim.sandboxaq.com/)
Large Quantitative Models for scientific discovery
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.aisim.sandboxaq.com/)
[Semrush(opens in new tab)](https://developer.semrush.com/api/introduction/semrush-mcp/)
SEO, market data, and brand visibility insights
URL
``` inline-block
https://mcp.semrush.com/claude/v1/mcp
```
[Shopify(opens in new tab)](https://help.shopify.com/en/manual/apps/connecting-ai-tools)
Build, manage, and analyze your Shopify store
URL
``` inline-block
https://setup.shopify.com/mcp
```
[Sigma(opens in new tab)](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
Query, search, and explore your data with Sigma
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
[SignNow(opens in new tab)](https://docs.signnow.com/docs/signnow/mcp-server)
Automate eSignature workflows directly from Claude
URL
``` inline-block
https://mcp-server.signnow.com/mcp
```
[Similarweb(opens in new tab)](https://docs.similarweb.com/api-v5/mcp/mcp-setup)
Real time web, mobile app, and market data.
URL
``` inline-block
https://mcp.similarweb.com
```
[Trimble SketchUp(opens in new tab)](https://help.sketchup.com/en/sketchup-claude-connector)
Create and iterate 3D models for use in SketchUp
URL
``` inline-block
https://api.sketchup.com/mcp/v1/sketchup/mcp
```
[Slack(opens in new tab)](https://docs.slack.dev/ai/mcp-server)
Send messages, create canvases, and fetch Slack data
URL
``` inline-block
https://mcp.slack.com/mcp
```
[Smartsheet(opens in new tab)](https://help.smartsheet.com/articles/2483663-use-smartsheet-connector-claude)
Analyze and manage Smartsheet data with Claude
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.smartsheet.com/articles/2483656-install-smartsheet-connector-claude#toc-get-started)
[Snowflake(opens in new tab)](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
Retrieve both structured and unstructured data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)
[Solve Intelligence(opens in new tab)](https://api.solveintelligence.com/guide/mcp/intro/)
Search, draft, and chart patents
URL
``` inline-block
https://api.solveintelligence.com/mcp/
```
[Sourcegraph(opens in new tab)](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
Give Claude full enterprise-scale codebase context.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
[Splice(opens in new tab)](https://support.splice.com/en/articles/14442749-getting-started-with-the-splice-mcp-server-beta)
Search Splice's sounds catalog, build stacks & more!
URL
``` inline-block
https://mcp.splice.com/mcp
```
[Spotify(opens in new tab)](https://support.spotify.com/)
Music and podcast recommendations, just for you.
URL
``` inline-block
https://mcp-gateway-external-pilot.spotify.net/mcp
```
[AdisInsight(opens in new tab)](https://adisinsight-mcp.springer.com)
Pharmaceutical drug & clinical trial intelligence
URL
``` inline-block
https://adisinsight-mcp.springer.com/mcp
```
[Order by Cash App(opens in new tab)](https://goose-docs.ai/docs/mcp/cash-app-mcp/)
Discover local food spots and order with a conversation
URL
``` inline-block
https://connect.squareup.com/v2/mcp/cash-app
```
[Square(opens in new tab)](https://developer.squareup.com/docs/mcp)
Search and manage transaction, merchant, and payment data
URL
``` inline-block
https://mcp.squareup.com/sse
```
[StubHub(opens in new tab)](https://support.stubhub.com/articles/61000310240-using-stubhub-in-chatgpt-and-claude)
Find tickets on the World's Largest Ticket Marketplace
URL
``` inline-block
https://open-ai-app.stubhub.net/mcp
```
[Superhuman Mail(opens in new tab)](https://help.superhuman.com/hc/en-us/articles/49810745762067-Superhuman-Mail-MCP-Server-Beta)
The most productive email app ever, for Gmail & Outlook
URL
``` inline-block
https://mcp.mail.superhuman.com/mcp
```
[Supermetrics Marketing Analytics(opens in new tab)](https://mcp.supermetrics.com/docs)
Google Ads, Facebook Ads & 200+ marketing platforms
URL
``` inline-block
https://mcp.supermetrics.com/mcp
```
[SurveyMonkey(opens in new tab)](https://www.surveymonkey.com/apps/BKcduxPnkCN4NFCRokUYCw_3D_3D/details/)
Design surveys, collect responses, and analyze results
URL
``` inline-block
https://mcp.surveymonkey.com/mcp
```
[Taskrabbit Booking Assistance(opens in new tab)](https://docs.google.com/document/d/1tWm33lJx4JdwN-Joqk7vydxQHaRGLod68wdS4k_hY9w/edit?tab=t.edb6z98lya3r#heading=h.2j0sep9c1ren)
Find & book local Taskrabbit services near you
URL
``` inline-block
https://mcp.taskrabbit.com/mcp
```
[Tavily(opens in new tab)](https://docs.tavily.com/documentation/mcp)
Connect your AI agents to the web
URL
``` inline-block
https://mcp.tavily.com/mcp
```
[Third Bridge(opens in new tab)](https://www.thirdbridge.com/en-us/data-solutions/mcp)
Expert-led enhanced insights
URL
``` inline-block
https://ai.thirdbridge.com/mcp/sse
```
[CoCounsel Legal(opens in new tab)](https://legal-mcp.thomsonreuters.com/docs/connector-guide)
Thomson Reuters CoCounsel Legal, in Claude
URL
``` inline-block
https://legal-mcp.thomsonreuters.com/mcp
```
[Thumbtack(opens in new tab)](https://docs.google.com/document/d/1RmGske5ktjAi9d7Ayok_yOv3a6Z2RDBSxIlX7aC5OEM/edit?usp=sharing)
Find and hire local pros in Claude
URL
``` inline-block
https://mcp.thumbtack.com/mcp
```
[Tines(opens in new tab)](https://www.tines.com/docs/actions/templates/mcp-server/)
Securely deploy servers in a matter of seconds in Tines
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://www.tines.com/docs/actions/templates/mcp-server/)
[tldraw(opens in new tab)](https://tldraw.notion.site/tldraw-mcp-app)
Let Claude sketch, draw, and diagram with you
URL
``` inline-block
https://tldraw-mcp-app.tldraw.workers.dev/mcp
```
[Tripadvisor(opens in new tab)](https://www.tripadvisor.com)
Find your perfect hotel based on Tripadvisor reviews
URL
``` inline-block
https://production.ai-mcp-extensibility-prd.tamg.cloud/ogMvjY4De1G7CiHanMOAgddl/mcp
```
[Turkish Airlines(opens in new tab)](https://mcp.turkishtechlab.com/)
Search flights, plan trips, and manage bookings
URL
``` inline-block
https://mcp-app.turkishtechlab.com/mcp
```
[Twilio(opens in new tab)](https://www.twilio.com/docs/ai/mcp)
Build powerful communications and customer engagement
URL
``` inline-block
https://mcp.twilio.com/docs
```
[Uber(opens in new tab)](https://www.uber.com/legal/en/)
Get Uber price & time estimates for any ride option
URL
``` inline-block
https://mcp.uber.com/claude/rides-3p/mcp
```
[Uber Eats(opens in new tab)](https://www.ubereats.com)
Explore restaurants and dishes
URL
``` inline-block
https://mcp.ubereats.com/eats-claude/mcp
```
[Udemy Business(opens in new tab)](https://business-support.udemy.com/hc/en-us/articles/34213384429335-How-to-Integrate-the-Udemy-Business-MCP-Server-With-Your-AI-Tool#h_01K9CA42YGCV1AVXPY1RKABKP1)
Search and explore skill-building resources
URL
``` inline-block
https://api.udemy.com/mcp
```
[Pylon(opens in new tab)](https://support.usepylon.com/articles/2407390554-connecting-to-the-pylon-mcp-server?lang=en)
Search and manage Pylon support issues
URL
``` inline-block
https://mcp.usepylon.com/
```
[Verisk Underwriting Intelligence(opens in new tab)](https://www.verisk.com/resources/verisk-underwriting-intelligence/)
Ask questions. Get underwriting insights from Verisk.
URL
``` inline-block
https://gatewaymcp.verisk.com/underwriting/intelligencemcp/v1
```
[Verisk XactRestore(opens in new tab)](https://veriskpropertyestimatingsolutions.my.site.com/s/article/2622)
Natural-language estimating for XactRestore
URL
``` inline-block
https://xactrestore-xactremodelserver-usw2-prod.propsol.io/mcp
```
[Viator(opens in new tab)](https://docs.viator.com/partner-api/mcp/)
Book travel experiences around the world
URL
``` inline-block
https://exp-app-mcp.prod.ep.viator.com/mcp
```
[Visier(opens in new tab)](https://docs.visier.com/developer/agents/mcp/mcp-server.htm)
Find people, productivity and business impact insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.visier.com/developer/agents/mcp/mcp-server-set-up.htm)
[Webflow(opens in new tab)](https://developers.webflow.com/mcp/v1.0.0/reference/overview)
Manage Webflow CMS, pages, assets and sites
URL
``` inline-block
https://mcp.webflow.com/mcp
```
[Wolfram(opens in new tab)](https://www.wolfram.com/artificial-intelligence/mcp-service/)
Inject precise, real-time computation and knowledge
URL
``` inline-block
https://agenttools.wolfram.com/mcp
```
[WordPress.com(opens in new tab)](https://developer.wordpress.com/docs/mcp/)
Secure AI access to manage your WordPress.com sites
URL
``` inline-block
https://public-api.wordpress.com/wpcom/v2/mcp/v1
```
[Workable(opens in new tab)](https://workable.readme.io/reference/workable-mcp-server)
Your AI assistant for Hiring and HR — inside Workable
URL
``` inline-block
https://mcp.workable.com/mcp
```
[Workato(opens in new tab)](https://docs.workato.com/en/mcp.html)
Automate workflows and connect your business apps
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://app.workato.com/ai_hub/mcp)
[Wyndham Hotels and Resorts(opens in new tab)](https://www.wyndhamhotels.com/mcp-doc)
Discover the right Wyndham Hotel for you, faster
URL
``` inline-block
https://mcp.wyndhamhotels.com/claude/mcp
```
[Xero(opens in new tab)](https://central.xero.com/s/article/Connect-Xero-using-the-Xero-connector-in-Claude?userregion=true)
Access your Xero financials from any conversation
URL
``` inline-block
https://mcp.xero.com/mcp
```
[Yardi Virtuoso(opens in new tab)](https://help.virtuoso.ai/en/articles/13679727-yardi-virtuoso-mcp-technical-documentation-guide)
Real-time Yardi data & insights
URL
``` inline-block
https://mcp.virtuoso.ai/mcp
```
[Zapier(opens in new tab)](https://docs.zapier.com/mcp/home)
Automate workflows across thousands of apps via conversation
URL
``` inline-block
https://mcp.zapier.com/api/v1/connect
```
[ZipRecruiter(opens in new tab)](https://api.ziprecruiter.com/mcp/docs)
Job search made easy
URL
``` inline-block
https://api.ziprecruiter.com/mcp
```
[Zoho Books(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Books MCP for Smart Finance Ops
[Zoho CRM(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
MCP Server for Zoho CRM Workflows
[Zoho Desk(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Desk MCP for Customer Support Automation
[Zoho Projects(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Projects MCP for Task & Project Automation
[ZoomInfo(opens in new tab)](https://docs.zoominfo.com/docs/zi-api-mcp-overview/)
Enrich contacts & accounts with GTM intelligence
URL
``` inline-block
https://mcp.zoominfo.com/mcp
```
[Tango(opens in new tab)](https://tango.makegov.com/docs/mcp/)
Search for US Government Contracting Data
URL
``` inline-block
https://govcon.dev/mcp
```
[Jam(opens in new tab)](https://jam.dev/docs/debug-a-jam/mcp)
Record screen and collect automatic context for issues
URL
``` inline-block
https://mcp.jam.dev/mcp
```
[Sentry(opens in new tab)](https://docs.sentry.io/product/sentry-mcp/)
Search, query, and debug errors intelligently
URL
``` inline-block
https://mcp.sentry.dev/mcp
```
[Stytch(opens in new tab)](https://stytch.com/docs/workspace-management/stytch-mcp)
Manage your Stytch Project
URL
``` inline-block
https://mcp.stytch.dev/mcp
```
[Craft(opens in new tab)](https://documents.craft.me/jWeCVJrSfxFRuA)
Notes & second brain
URL
``` inline-block
https://mcp.craft.do/my/mcp
```
[Alma(opens in new tab)](https://alma.food/mcp)
Your nutrition data, inside every Claude conversation.
URL
``` inline-block
https://mcp.alma.food
```
[MoSPI(opens in new tab)](https://www.datainnovation.mospi.gov.in/mospi-mcp)
India's official statistics via natural language
URL
``` inline-block
https://mcp.mospi.gov.in/
```
[Adobe for creativity(opens in new tab)](https://developer.adobe.com/adobe-for-creativity/)
Ideate, create, and deliver with Adobe pro tools
URL
``` inline-block
https://adobe-creativity.adobe.io/mcp
```
[Adobe Journey Optimizer(opens in new tab)](https://experienceleague.adobe.com/en/docs/journey-optimizer/using/content-management/combine/ajo-mcp)
Understand and troubleshoot your Journeys and Campaigns
URL
``` inline-block
https://ajo-mcp.adobe.io/mcp
```
[Adobe Marketing Agent(opens in new tab)](https://acrobat.adobe.com/id/urn:aaid:sc:AP:5799e952-be87-4829-b0c4-6f82ca8e8b8b)
Marketing campaign and audience insights from Adobe
URL
``` inline-block
https://aep-ai-ama.adobe.io/mcp
```
[Common Room(opens in new tab)](https://www.commonroom.io/docs/using-common-room/common-room-for-claude-connector-and-plugin/)
Your GTM Copilot
URL
``` inline-block
https://mcp.commonroom.io/mcp
```
[Customer.io(opens in new tab)](https://docs.customer.io/ai/mcp-server/)
Explore customer data and generate insights via Claude
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.customer.io/ai/mcp-server/)
[Eraser(opens in new tab)](https://docs.eraser.io/docs/mcp)
Generate, manage, and update Eraser diagrams and files
URL
``` inline-block
https://app.eraser.io/api/mcp
```
[Harness.io(opens in new tab)](https://github.com/harness/mcp-server)
Build, Ship and Secure your apps on Harness Platform
URL
``` inline-block
https://mcp.harness.io/mcp
```
[Honeycomb(opens in new tab)](https://docs.honeycomb.io/troubleshoot/product-lifecycle/beta/mcp/)
Query and explore observability data and SLOs
URL
``` inline-block
https://mcp.honeycomb.io/mcp
```
[incident.io(opens in new tab)](https://docs.incident.io/ai/remote-mcp)
See and manage everything in incident.io
URL
``` inline-block
https://mcp.incident.io/mcp
```
[n8n(opens in new tab)](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
Access and run your n8n workflows
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
[Pendo(opens in new tab)](https://support.pendo.io/hc/en-us/articles/41102236924955)
Connect to Pendo for product and user insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://support.pendo.io/hc/en-us/articles/41102236924955)
[Sanity(opens in new tab)](https://www.sanity.io/docs/ai/mcp-server)
Create, query, and manage structured content in Sanity
URL
``` inline-block
https://mcp.sanity.io
```
[Starburst(opens in new tab)](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
Securely retrieve data from your federated data sources
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
[tldv(opens in new tab)](https://tldv.notion.site/tl-dv-MCP-Official-Documentation-330cce15f3ba80638f5ac0253e3b8fd4?source=copy_link)
Fetch Transcripts & Notes from Meet, Zoom & Teams
URL
``` inline-block
https://mcp.tldv.io/mcp
```
[Tropic(opens in new tab)](https://help.tropicapp.io/hc/en-us/articles/45502083594267-Using-Model-Context-Protocol-MCP-with-Tropic)
Save money on Software + AI contracts
URL
``` inline-block
https://app.tropicapp.io/mcp
```
[Unthread(opens in new tab)](https://docs.unthread.io/docs/unthread-ai/unthread-mcp)
Manage and automate your support tickets
URL
``` inline-block
https://app.unthread.io/api/mcp
```
[Zocks(opens in new tab)](https://help.zocks.io/en/articles/14075856-connect-to-the-zocks-mcp-server)
Analyze client conversations, patterns, and insights.
URL
``` inline-block
https://mcp.zocks.io/v1/mcp
```
[Trellis(opens in new tab)](https://support.trellis.law)
Claude for Trial Court Litigators
URL
``` inline-block
https://mcp.trellis.law/anthropic
```
[Todoist(opens in new tab)](https://github.com/Doist/todoist-ai)
Search, complete, and manage your tasks in Todoist
URL
``` inline-block
https://ai.todoist.net/mcp
```
[Relativity(opens in new tab)](https://help.relativity.com/topic.html?t=GLJ39)
Organize Data. Discover the Truth. Act on It.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.relativity.com/topic.html?t=GLJ39)
[BoardWise(opens in new tab)](https://boardwise.online/mcp)
Calm board-defense guidance for licensed pros.
URL
``` inline-block
https://uakozrqrztgrgwoywxkx.supabase.co/functions/v1/mcp-server
```
[Candid(opens in new tab)](https://support.claude.com/en/articles/12923235-using-the-candid-connector-in-claude)
Research nonprofits and funders using Candid's data
URL
``` inline-block
https://mcp.candid.org/mcp
```
[Learning Commons Knowledge Graph(opens in new tab)](https://docs.learningcommons.org/knowledge-graph/integrations/claude)
K-12 standards, skills, and learning progressions
URL
``` inline-block
https://kg.mcp.learningcommons.org/mcp
```
[Open Targets(opens in new tab)](https://github.com/opentargets/open-targets-platform-mcp)
Drug target discovery and prioritisation platform
URL
``` inline-block
https://mcp.platform.opentargets.org/mcp
```
[Synapse.org(opens in new tab)](https://github.com/susheel/synapse-mcp?tab=readme-ov-file#synapse-mcp-server)
Search and metadata tools for Synapse scientific data
URL
``` inline-block
https://mcp.synapse.org/mcp
```
[Chronograph(opens in new tab)](https://lp-help.chronograph.pe/article/735-chronograph-mcp)
Interact with your Chronograph data directly in Claude
URL
``` inline-block
https://ai.chronograph.pe/mcp
```
[Hex(opens in new tab)](https://learn.hex.tech/docs/administration/mcp-server)
Answer questions with the Hex agent
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://learn.hex.tech/docs/administration/mcp-server#connect-to-claude)
[Zoom for Claude(opens in new tab)](https://developers.zoom.us/docs/mcp/zoom/)
Search, recap, and act on your Zoom meetings
URL
``` inline-block
https://mcp.zoom.us/mcp/zoom/streamable
```
**Looking for more?** [Find hundreds more MCP servers on GitHub](https://github.com/modelcontextprotocol/servers).
---
## Agents-Tools/agents-and-tools-tool-use-advisor-tool-0a75684a7b.md
# Advisor tool
Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.
---
The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction (typically 400 to 700 text tokens, 1,400 to 1,800 tokens total including thinking), and the executor continues with the task.
This pattern fits long-horizon agentic workloads (coding agents, computer use, multi-step research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates.
<Note>
The advisor tool is in beta. Include the beta header `advisor-tool-2026-03-01`
in your requests. To request access or share feedback, contact your Anthropic
account team.
</Note>
<Note>
This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
</Note>
## When to use it
Early benchmarks show meaningful gains for these configurations:
- **You currently use Sonnet on complex tasks:** Add Opus as the advisor for a quality lift at similar or lower total cost.
- **You currently use Haiku and want a step up in intelligence:** Add Opus as the advisor. Expect higher cost than Haiku alone, but lower than switching the executor to a larger model.
Results are task-dependent. Evaluate on your own workload.
The advisor is a weaker fit for single-turn Q&A (nothing to plan), pure pass-through model pickers where your users already choose their own cost and quality tradeoff, or workloads where every turn genuinely requires the advisor model's full capability.
## Model compatibility
The executor model (the top-level `model` field) and the advisor model (the `model` field inside the tool definition) must form a valid pair. The advisor must be at least as capable as the executor.
| Executor models | Advisor models |
| ---------------------------------------------- | ----------------------------------- |
| Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) | Claude Opus 4.7 (`claude-opus-4-7`) |
| Claude Sonnet 4.6 (`claude-sonnet-4-6`) | Claude Opus 4.7 (`claude-opus-4-7`) |
| Claude Opus 4.6 (`claude-opus-4-6`) | Claude Opus 4.7 (`claude-opus-4-7`) |
| Claude Opus 4.7 (`claude-opus-4-7`) | Claude Opus 4.7 (`claude-opus-4-7`) |
If you request an invalid pair, the API returns a `400 invalid_request_error` naming the unsupported combination.
## Platform availability
The advisor tool is available in beta on the Claude API (Anthropic).
## Quick start
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advisor-tool-2026-03-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-6",
"max_tokens": 4096,
"tools": [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7"
}
],
"messages": [{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown."
}]
}'
```
```bash CLI
ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'
model: claude-sonnet-4-6
max_tokens: 4096
tools:
- type: advisor_20260301
name: advisor
model: claude-opus-4-7
messages:
- role: user
content: Build a concurrent worker pool in Go with graceful shutdown.
YAML
```
```python Python hidelines={1..2}
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=[
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7",
}
],
messages=[
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
],
)
print(response)
```
```typescript TypeScript hidelines={1..5,-3..-1}
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
async function main() {
const response = await client.beta.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 4096,
betas: ["advisor-tool-2026-03-01"],
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-4-7"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
]
});
console.log(response);
}
main().catch(console.error);
```
```csharp C# nocheck hidelines={1}
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet4_6,
MaxTokens = 4096,
Tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus4_7
}
},
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "Build a concurrent worker pool in Go with graceful shutdown."
}
],
Betas = ["advisor-tool-2026-03-01"]
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go nocheck hidelines={1..11,-1}
package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet4_6,
MaxTokens: 4096,
Tools: []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus4_7,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
}
```
```php PHP hidelines={1..4}
<?php
use Anthropic\Client;
$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
[
'role' => 'user',
'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',
],
],
model: 'claude-sonnet-4-6',
tools: [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-4-7',
],
],
betas: ['advisor-tool-2026-03-01'],
);
echo $response;
```
```ruby Ruby hidelines={1..2}
require "anthropic"
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-sonnet-4-6",
max_tokens: 4096,
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-4-7"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
],
betas: ["advisor-tool-2026-03-01"]
)
puts response
```
</CodeGroup>
## How it works
When you add the advisor tool to your `tools` array, the executor model decides when to call it, just like any other tool. When the executor invokes the advisor:
1. The executor emits a `server_tool_use` block with `name: "advisor"` and an empty `input`. The executor signals timing; the server supplies context.
2. Anthropic runs a separate inference pass on the advisor model server-side, passing the executor's full transcript. The advisor sees the system prompt, all tool definitions, all prior turns, and all prior tool results.
3. The advisor's response returns to the executor as an `advisor_tool_result` block.
4. The executor continues generating, informed by the advice.
All of this happens inside a single `/v1/messages` request. No extra round trips on your side.
The advisor itself runs without tools and without context management. Its thinking blocks are dropped before the result returns; only the advice text reaches the executor.
## Tool parameters
| Parameter | Type | Default | Description |
| ----------------------- | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | _required_ | Must be `"advisor_20260301"`. |
| `name` | string | _required_ | Must be `"advisor"`. |
| `model` | string | _required_ | The advisor model ID, such as `"claude-opus-4-7"`. Billed at this model's rates for the sub-inference. |
| `max_uses` | integer | unlimited | Maximum number of advisor calls allowed in a single request. Once the executor reaches this cap, further advisor calls return an `advisor_tool_result_error` with `error_code: "max_uses_exceeded"` and the executor continues without further advice. This is a per-request cap, not a per-conversation cap; see [Cost control](#cost-control) for conversation-level limits. |
| `caching` | object \| null | `null` (off) | Enables prompt caching for the advisor's own transcript across calls within a conversation. See [Advisor prompt caching](#advisor-prompt-caching). |
The `caching` object has the shape `{"type": "ephemeral", "ttl": "5m" | "1h"}`. Unlike `cache_control` on content blocks, this is not a breakpoint marker; it is an on/off switch. The server decides where cache boundaries go.
## Response structure
### Successful advisor call
When the advisor is invoked, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content:
```json
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Let me consult the advisor on this."
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "advisor",
"input": {}
},
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_result",
"text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
}
},
{
"type": "text",
"text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
}
]
}
```
The `server_tool_use.input` is always empty. The server constructs the advisor's view from the full transcript automatically; nothing the executor puts in `input` reaches the advisor.
### Result variants
The `advisor_tool_result.content` field is a discriminated union. Which variant you receive depends on the advisor model:
| Variant | Fields | Returned when |
| ------------------------- | ------------------- | ------------------------------------------------------------------- |
| `advisor_result` | `text` | The advisor model returns plaintext (for example, Claude Opus 4.7). |
| `advisor_redacted_result` | `encrypted_content` | The advisor model returns encrypted output. |
With `advisor_result`, the `text` field contains human-readable advice. With `advisor_redacted_result`, the `encrypted_content` field contains an opaque blob that you cannot read; on the next turn, the server decrypts it and renders the plaintext into the executor's prompt.
In both cases, round-trip the content verbatim on subsequent turns. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes.
### Error results
If the advisor call fails, the result carries an error:
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_tool_result_error",
"error_code": "overloaded"
}
}
```
The executor sees the error and continues without further advice. The request itself does not fail.
| `error_code` | Meaning |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `max_uses_exceeded` | The request reached the `max_uses` cap set on the tool definition. Further advisor calls in the same request return this error. |
| `too_many_requests` | The advisor sub-inference was rate-limited. |
| `overloaded` | The advisor sub-inference hit capacity limits. |
| `prompt_too_long` | The transcript exceeded the advisor model's context window. |
| `execution_time_exceeded` | The advisor sub-inference timed out. |
| `unavailable` | Any other advisor failure. |
Advisor rate limits draw from the same per-model bucket as direct calls to the advisor model. A rate limit on the advisor appears as `too_many_requests` inside the tool result; a rate limit on the executor fails the whole request with HTTP 429.
## Multi-turn conversations
Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns:
```python
import anthropic
client = anthropic.Anthropic()
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7",
}
]
messages = [
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
]
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})
# Continue the conversation
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
```
If you omit the advisor tool from `tools` on a follow-up turn while the message history still contains `advisor_tool_result` blocks, the API returns a `400 invalid_request_error`.
<Note>
The advisor tool has no built-in conversation-level cap. To limit advisor
calls across a conversation, count them client-side. When you reach your
ceiling, remove the advisor tool from your `tools` array **and** strip all
`advisor_tool_result` blocks from your message history to avoid a
`400 invalid_request_error`.
</Note>
## Streaming
The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs, then the full result arrives in a single event.
The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds; short advisor calls may show no pings.
When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming.
A `message_delta` event follows with the updated `usage.iterations` array reflecting the advisor's token counts.
## Usage and billing
Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array:
```json
{
"usage": {
"input_tokens": 412,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 531,
"iterations": [
{
"type": "message",
"input_tokens": 412,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 89
},
{
"type": "advisor_message",
"model": "claude-opus-4-7",
"input_tokens": 823,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 1612
},
{
"type": "message",
"input_tokens": 1348,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 442
}
]
}
}
```
Top-level `usage` fields reflect executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at a different rate. Iterations with `type: "advisor_message"` are billed at the advisor model's rates; iterations with `type: "message"` are billed at the executor model's rates.
The aggregation rules differ by field. Top-level `output_tokens` is the sum of all executor iterations. Top-level `input_tokens` and `cache_read_input_tokens` reflect the first executor iteration only; subsequent executor iterations' inputs are not re-summed because they include prior output tokens. Use `usage.iterations` for a full per-iteration breakdown when building cost-tracking logic.
Advisor output is typically 400 to 700 text tokens, or 1,400 to 1,800 tokens total including thinking. The cost savings come from the advisor not generating your full final output; the executor does that at its lower rate.
The top-level `max_tokens` applies to executor output only. It does not bound advisor sub-inference tokens. The advisor's tokens also do not draw from any task budget applied to the executor.
## Advisor prompt caching
There are two independent caching layers.
### Executor-side caching
The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it on a subsequent turn will hit. The executor's prompt always contains the plaintext advice regardless of whether your client received `text` or `encrypted_content`, so caching behavior is identical for both result variants.
### Advisor-side caching
Set `caching` on the tool definition to enable prompt caching for the advisor's own transcript across calls within the same conversation:
```python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry; the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become nonzero on the second and later `advisor_message` iterations.
**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops; keep it off for short tasks.
**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.
<Warning>
[`clear_thinking`](/docs/en/build-with-claude/context-editing) with a `keep`
value other than `"all"` shifts the advisor's quoted transcript each turn,
causing advisor-side cache misses. This is a cost degradation only; advice
quality is unaffected. When extended thinking is enabled without explicit
`clear_thinking` configuration, the API defaults to
`keep: {type: "thinking_turns", value: 1}`, which triggers this behavior.
Set `keep: "all"` to preserve advisor cache stability.
</Warning>
## Combining with other tools
The advisor tool composes with other server-side and client-side tools. Add them all to the same `tools` array:
```python
tools = [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
},
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-4-7",
},
{
"name": "run_bash",
"description": "Run a bash command",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
},
},
]
```
The executor can search the web, call the advisor, and use your custom tools in the same turn. The advisor's plan can inform which tools the executor reaches for next.
| Feature | Interaction |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Batch processing](/docs/en/build-with-claude/batch-processing) | Supported. `usage.iterations` is reported per item. |
| [Token counting](/docs/en/build-with-claude/token-counting) | Returns the executor's first-iteration input tokens only. For a rough advisor estimate, call `count_tokens` with `model` set to the advisor model and the same messages. |
| [Context editing](/docs/en/build-with-claude/context-editing) | `clear_tool_uses` is not yet fully compatible with advisor tool blocks; full support is planned for a follow-up release. With `clear_thinking`, see the caching warning above. |
| `pause_turn` | A dangling advisor call ends the response with `stop_reason: "pause_turn"` and the `server_tool_use` block as the last content block. The advisor executes on resumption. See [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |
## Best practices
### Prompting for coding and agent tasks
The advisor tool ships with a built-in description that nudges the executor to call it near the start of complex tasks and when it hits difficulty. For research tasks, no additional prompting is typically needed.
On coding and agent tasks, the advisor produces higher intelligence at similar cost when it reduces total tool calls and conversation length. Two timings drive this improvement:
1. An early first advisor call, after a few exploratory reads are in the transcript.
2. For difficult tasks, a final advisor call after file writes and test outputs are in the transcript.
If your agent exposes other planner-like tools (for example, a todo list tool), prompt the model to call the advisor before those tools so the advisor's plan funnels into them. The suggested system prompt below reinforces the early-call pattern; add your own funnel-in sentence pointing at whichever planner tools your agent exposes.
#### Suggested system prompt for coding tasks
For coding tasks where you want consistent advisor timing and around two to three calls per task, prepend the following blocks to your executor system prompt before any other sentences that mention the advisor. On internal coding evaluations this pattern produced the highest intelligence at near-Sonnet cost.
Timing guidance:
```text
You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
```
How the executor should treat the advice (place directly after the timing block):
```text
Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.
If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.
```
#### Trimming advisor output length
Advisor output is the advisor's largest cost driver. To reduce that cost, prepend a single conciseness instruction to the system prompt before any other sentence that mentions the advisor. In internal testing, the following line cut total advisor output tokens by roughly 35 to 45 percent without changing call frequency:
```text
The advisor should respond in under 100 words and use enumerated steps, not explanations.
```
Pair this with the timing block above for the strongest cost-versus-quality tradeoff.
### Pairing with effort settings
For coding tasks, pairing a Sonnet executor at medium [effort](/docs/en/build-with-claude/effort) with an Opus advisor achieves intelligence comparable to Sonnet at default effort, at lower cost. For maximum intelligence, keep the executor at default effort.
### Cost control
- For conversation-level budgets, count advisor calls client-side. When you reach your cap, remove the advisor tool from `tools` **and** strip all `advisor_tool_result` blocks from your message history to avoid a `400 invalid_request_error`.
- Enable `caching` only for conversations where you expect three or more advisor calls.
## Limitations
- **Advisor output does not stream.** Expect a pause in the stream while the sub-inference runs.
- **No built-in conversation-level cap on advisor calls.** Track and cap them client-side.
- **`max_tokens` applies to executor output only.** It does not bound advisor tokens.
- **Anthropic Priority Tier** is honored per model. Priority Tier on the executor model does not extend to the advisor; you need Priority Tier on the advisor model specifically.
---
## Agents-Tools/agents-and-tools-tool-use-advisor-tool-4e22ba57ce.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fadvisor-tool)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Tools
# Advisor tool
Copy page
Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.
Copy page
The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction, and the executor continues with the task.
This pattern fits long-horizon agentic workloads (coding agents, computer use, multistep research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates. For measured results, including how the benefit shrinks as the executor's own capability approaches the advisor's, see [Optimizing for cost and intelligence](/docs/en/about-claude/models/optimizing-for-cost-and-intelligence).
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
## When to use it
The advisor fits these configurations:
- **You currently use Sonnet on complex tasks:** Add a higher-tier advisor. Opus keeps total cost similar or lower; Claude Fable 5.1 maximizes the quality lift.
- **You currently use Haiku and want a step up in intelligence:** Add an Opus or Fable advisor. Expect higher cost than Haiku alone, but lower than switching the executor to a larger model.
Results are task-dependent. Evaluate on your own workload.
The advisor is a weaker fit for single-turn Q&A (nothing to plan), pure pass-through model pickers where your users already choose their own cost and quality tradeoff, or workloads where every turn genuinely requires the advisor model's full capability.
## Quick start
The advisor tool is in beta. Include the beta header `advisor-tool-2026-03-01` in your requests.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=[
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
}
],
messages=[
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
],
)
print(response)
```
The response `content` includes an `advisor_tool_result` block carrying the advisor's guidance. With `claude-opus-5` as the advisor, as in this quick start, the block's `content` field is an `advisor_redacted_result` variant (encrypted; the executor reads it server-side, but your client does not). To see the advice text directly in your response, use `claude-opus-4-8` as the advisor model instead, which returns the plaintext `advisor_result` variant. See [Result variants](#result-variants) for both shapes side by side and which advisor models return which, and [Model compatibility](#model-compatibility) for the full list of valid pairs.
## How it works
When you add the advisor tool to your `tools` array, the executor model determines when to call it, like any other tool. When the executor calls the advisor:
1. The executor emits a [`server_tool_use`](/docs/en/agents-and-tools/tool-use/server-tools) block with `name: "advisor"` and an empty `input`. The executor signals timing, and the server supplies context.
2. Anthropic runs a separate inference pass on the advisor model server-side. The advisor runs under its own Anthropic-supplied system prompt and receives the executor's full transcript as quoted context in its input. That transcript includes your system prompt, the tool definitions, the prior turns and tool results, and the text the executor has produced so far in this turn.
3. The advisor's response returns to the executor as an `advisor_tool_result` block.
4. The executor continues generating, informed by the advice.
All of this occurs inside a single `/v1/messages` request, with no extra round trips on your side. The exception is a turn that pauses mid-call, which you resume with a follow-up request (see [Resuming a paused turn](#resuming-a-paused-turn)).
The advisor itself runs without tools and without context management. Its thinking blocks are dropped before the result returns. Only the advice text reaches the executor.
## Tool parameters
[TABLE]
The `caching` object has the shape `{"type": "ephemeral", "ttl": "5m" | "1h"}`. Unlike `cache_control` on content blocks, this is not a breakpoint marker. It is an on/off switch. The server determines where cache boundaries go.
The advisor tool also accepts the generic properties available on any tool definition: `cache_control`, `allowed_callers`, `defer_loading`, and `strict` (covered in [structured outputs](/docs/en/build-with-claude/structured-outputs)). See the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference#tool-definition-properties) for their semantics.
## Response structure
### Successful advisor call
When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](#quick-start) uses Claude Opus 5, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](#result-variants) for both shapes side by side.
```python
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Let me consult the advisor on this."
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "advisor",
"input": {}
},
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_result",
"text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
}
},
{
"type": "text",
"text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
}
]
}
```
The `server_tool_use.input` is always empty. The server constructs the advisor's view from the full transcript automatically. Nothing the executor puts in `input` reaches the advisor.
### Result variants
The `advisor_tool_result.content` field is a discriminated union. For successful calls, the variant depends on the advisor model:
| Variant | Fields | Returned when |
|---------------------------|------------------------------------|---------------------------------------------------------------------|
| `advisor_result` | `text`, `stop_reason` | The advisor model returns plaintext (for example, Claude Opus 4.8). |
| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | The advisor model returns encrypted output. |
Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5 advisors return the encrypted `advisor_redacted_result`. Every other advisor model in the [compatibility table](#model-compatibility) returns the plaintext `advisor_result`. To read the advice text in your own responses, use an advisor that returns plaintext, such as `claude-opus-4-8`, where your executor's row in the [compatibility table](#model-compatibility) lists one. Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5 executors pair only with advisors that return the encrypted form, so on those executors the advice text isn't readable in the response.
Here is the same request sent twice, identical except for the advisor `model` in the tool definition, showing both variants.
With `"model": "claude-opus-4-8"`, the advice is plaintext:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_result",
"text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
}
}
```
With `"model": "claude-opus-5"`, the advice is encrypted:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
}
}
```
Both result variants carry a `stop_reason` field when you set [`max_tokens`](#capping-advisor-output) on the tool definition, and omit it when you do not. It holds the advisor sub-call's stop reason, typically `"end_turn"`, or `"max_tokens"` when the cap is hit. The values match the top-level Messages API [`stop_reason`](/docs/en/build-with-claude/handling-stop-reasons).
With `advisor_result`, the `text` field contains human-readable advice. With `advisor_redacted_result`, the `encrypted_content` field contains an opaque blob that you cannot read. On the next turn, the server decrypts it and renders the plaintext into the executor's prompt.
In both cases, round-trip the content verbatim on subsequent turns. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes.
### Error results
If the advisor call fails, the result carries an error:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_tool_result_error",
"error_code": "overloaded"
}
}
```
The executor sees the error and continues without further advice. The request itself does not fail.
| `error_code` | Meaning |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `max_uses_exceeded` | The request reached the `max_uses` cap set on the tool definition. Further advisor calls in the same request return this error. |
| `too_many_requests` | The advisor sub-inference was rate-limited. |
| `overloaded` | The advisor sub-inference hit capacity limits. |
| `prompt_too_long` | The transcript exceeded the advisor model's context window. |
| `execution_time_exceeded` | The advisor sub-inference timed out. |
| `model_not_found` | The configured advisor model is not available. |
| `unavailable` | Any other advisor failure. |
Advisor rate limits draw from the same per-model bucket as direct calls to the advisor model. A rate limit on the advisor appears as `too_many_requests` inside the tool result. A rate limit on the executor fails the whole request with HTTP 429.
## Multi-turn conversations
Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with a Claude Opus 5 advisor the result block's `content` is the encrypted `advisor_redacted_result` variant, and the server decrypts it and renders the advice into the executor's prompt on the next turn (see [Result variants](#result-variants)). The mechanics are identical for any advisor model.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
}
]
messages = [
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
]
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})
# Continue the conversation
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
```
You can drop the advisor tool from `tools` on a follow-up turn while the message history still contains `advisor_tool_result` blocks. The request is accepted and the historical blocks are preserved; the model cannot call the advisor on that turn. You must still send the `advisor-tool-2026-03-01` beta header for those history blocks to be accepted.
The advisor tool has no built-in conversation-level cap. To limit advisor calls across a conversation, count them client-side. When you reach your ceiling, remove the advisor tool from your `tools` array. You do not need to strip `advisor_tool_result` blocks from your message history.
### Resuming a paused turn
A response can end with `stop_reason: "pause_turn"` while an advisor call is still pending. When that occurs, the response contains the advisor's `server_tool_use` block with no `advisor_tool_result` for it. To resume, append that assistant message to `messages` with its content unchanged, keeping the `server_tool_use` block, and send the request again with the same advisor tool and beta header. You do not need to add a user message or a `tool_result` block. The API runs the pending advisor call and continues the executor's turn in the new response. A resumed turn can pause again. If it does, repeat the same step. Omitting the advisor tool from the resume request returns a 400 `invalid_request_error`, because the pending `server_tool_use` block has no tool definition to run against; include the tool whenever a call is pending. If instead the executor called one of your tools in the same turn, the response ends with `stop_reason: "tool_use"` while the advisor call is still pending. Send the `tool_result` blocks as usual, and the pending advisor call runs at the start of that next request. See [Mixing server tools and client tools in one turn](/docs/en/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
### Mid-conversation nudge for under-calling executors
If a Haiku executor has not called the advisor in its first assistant turn, append a short reminder as an additional user message before the second assistant turn. In Anthropic's internal behavioral evaluation this raised task pass rates by roughly 7 percentage points on Haiku executors. On Sonnet executors, the plain-text nudge had no measurable effect in Anthropic's testing. The call-timing considerations that follow are especially relevant for Sonnet. Do not apply the nudge to Opus executors: On Opus it slightly lowered pass rates.
With the default `NUDGE_TURN` of 2, the reminder typically arrives after the model has oriented on the task but before it has committed to an approach.
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
"You have not consulted the advisor yet. If the task has a non-obvious "
"design decision or a failure mode you haven't ruled out, call advisor "
"now before committing to an approach."
)
MAX_TURNS = 10 # agent loop cap
def run_your_tools(content):
# Replace with your tool dispatch. Returns one tool_result block per tool_use block.
return [
{
"type": "tool_result",
"tool_use_id": block.id,
"content": "Replace with your tool output.",
}
for block in content
if block.type == "tool_use"
]
tools = [
{"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
# ... your other tools
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False
for turn in range(1, MAX_TURNS + 1):
response = client.beta.messages.create(
model="claude-haiku-4-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
advisor_called = advisor_called or any(
block.type == "server_tool_use" and block.name == "advisor"
for block in response.content
)
if response.stop_reason == "end_turn":
break
if response.stop_reason == "pause_turn":
continue # server tool pending; re-send to let the API complete it
results = run_your_tools(response.content) # list of tool_result blocks
if results:
messages.append({"role": "user", "content": results})
# Skip this if your system prompt already tells the model to call sparingly.
if turn == NUDGE_TURN - 1 and not advisor_called:
messages.append({"role": "user", "content": NUDGE_TEXT})
```
Append the nudge as its own user message after the tool results rather than as a sibling block in the same message. Consecutive user messages are valid. In Anthropic's testing on Haiku and Sonnet executors they behaved equivalently to a sibling block. The separate-message shape also keeps the reminder clearly distinct from tool output.
**Trade-offs:** The nudge raises the call rate, which can push trivially simple tasks into an unnecessary consult. If your workload mixes simple and complex tasks, consider raising `NUDGE_TURN` to 3 so two-turn tasks complete before the nudge fires, or gate the nudge on a task-complexity signal you already compute. If your system prompt already contains restraint language ("reserve the advisor for genuine uncertainty"), skip the nudge entirely, because the two instructions conflict.
The plain-text nudge is highly salient on Haiku and Sonnet executors: 74 percent (Sonnet) to 98 percent (Haiku) of nudged attempts in Anthropic's testing called the advisor immediately at turn 2. If that lands before your executor has read the problem or gathered context, the resulting advisor call is low-context and can displace a better-timed later call. Measure your executor's baseline first-call turn before adding the nudge. If the executor already calls the advisor reliably and its first call typically lands at turn N, set `NUDGE_TURN` greater than N. In Anthropic's testing, a turn-2 nudge on workloads where the baseline first call was turn 7 or later correlated with a 3 to 4 percentage-point task-performance drop. On a browse workload where the baseline call rate was 86 percent, the same nudge raised engagement with no task-performance cost.
To force a consult on a specific request instead of nudging, set `tool_choice` to `{"type": "tool", "name": "advisor"}`, subject to the constraints in [Forcing tool use](/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use). Forcing tool use cannot be combined with manual extended thinking (`thinking: {type: "enabled"}`): the API returns a `400 invalid_request_error` if you enable both. Adaptive thinking supports forced tool use. Claude Fable 5.1 and Claude Mythos 5.1 executors reject `tool_choice` types `tool` and `any`, so use the prompt nudge on those models instead.
## Streaming
The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs; then the full result arrives in a single event.
The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds. Short advisor calls might show no pings.
When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming.
A `message_delta` event follows with the updated `usage.iterations` array reflecting the advisor's token counts.
## Usage and billing
Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array:
```python
{
"usage": {
"input_tokens": 1760,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 531,
"iterations": [
{
"type": "message",
"input_tokens": 412,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 89
},
{
"type": "advisor_message",
"model": "claude-opus-5",
"input_tokens": 823,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 1612
},
{
"type": "message",
"input_tokens": 1348,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 442
}
]
}
}
```
Top-level `usage` fields reflect executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at a different rate. Iterations with `type: "advisor_message"` are billed at the advisor model's rates, and iterations with `type: "message"` are billed at the executor model's rates.
Every top-level `usage` field is the sum of that field across all executor iterations, including `input_tokens`, `output_tokens`, and `cache_read_input_tokens`. Because each executor iteration re-sends the growing conversation, later iterations' inputs include earlier iterations' output, so summed `input_tokens` exceeds the size of any single prompt. Use `usage.iterations` for a full per-iteration breakdown when building cost-tracking logic.
Advisor output is typically 400 to 700 text tokens, or 1,400 to 1,800 tokens total including thinking. The cost savings come from the advisor not generating your full final output. The executor does that at its lower rate.
The top-level `max_tokens` applies to executor output only. It does not bound advisor sub-inference tokens. To cap advisor output directly, set [`max_tokens` on the tool definition](#capping-advisor-output). The advisor's tokens also do not draw from any [task budget](/docs/en/build-with-claude/task-budgets) applied to the executor.
[Priority Tier](/docs/en/api/service-tiers) applies to each model independently. A Priority Tier commitment on the executor model does not extend to the advisor. Advisor calls run at Priority Tier only if your organization also holds a commitment on the advisor model.
## Advisor prompt caching
There are two independent caching layers.
### Executor-side caching
The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it on a subsequent turn hits. The executor's prompt always contains the plaintext advice regardless of whether your client received `text` or `encrypted_content`, so caching behavior is identical for both result variants.
### Advisor-side caching
Set `caching` on the tool definition to enable prompt caching for the advisor's own transcript across calls within the same conversation:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry, and the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become non-zero on the second and later `advisor_message` iterations.
**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops, and keep it off for short tasks.
**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.
[`clear_thinking`](/docs/en/build-with-claude/context-editing) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only. Advice quality is unaffected. When extended thinking is enabled without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus/Sonnet models and all Haiku models, whereas on Opus 4.5+ and Sonnet 4.6+ the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
## Combining with other tools
The advisor tool composes with other server-side and client-side tools. Add them all to the same `tools` array:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
tools = [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
},
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
},
{
"name": "run_bash",
"description": "Run a bash command",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
},
},
]
```
The executor can search the web, call the advisor, and use your custom tools in the same turn. The advisor's plan can inform which tools the executor reaches for next.
| Feature | Interaction |
|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Batch processing](/docs/en/build-with-claude/batch-processing) | Supported. `usage.iterations` is reported per item. |
| [Token counting](/docs/en/build-with-claude/token-counting) | Returns the executor's first-iteration input tokens only. For a rough advisor estimate, call `count_tokens` with `model` set to the advisor model and the same messages. |
| [Context editing](/docs/en/build-with-claude/context-editing) | `clear_tool_uses` is not fully compatible with advisor tool blocks. With `clear_thinking`, see the earlier caching warning. |
| `pause_turn` | A dangling advisor call ends the response with `stop_reason: "pause_turn"` and a `server_tool_use` block with no result when no client `tool_use` block is awaiting your result in the same turn. The advisor runs on resumption. If the executor also called one of your tools in that turn, the response ends with `stop_reason: "tool_use"` instead, and the pending advisor call runs at the start of your next request, after you send the `tool_result` blocks. See [Resuming a paused turn](#resuming-a-paused-turn), [Mixing server tools and client tools in one turn](/docs/en/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn), and [Server tools](/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |
## Best practices
### Prompting for coding and agent tasks
The advisor tool ships with a built-in description that nudges the executor to call it near the start of complex tasks and when it hits difficulty. For research tasks, no additional prompting is typically needed.
On coding and agent tasks, the advisor produces higher intelligence at similar cost when it reduces total tool calls and conversation length. Two timings drive this improvement:
1. An early first advisor call, after a few exploratory reads are in the transcript.
2. For difficult tasks, a final advisor call after file writes and test outputs are in the transcript.
If your agent exposes other planner-like tools (for example, a todo list tool), prompt the model to call the advisor before those tools so the advisor's plan funnels into them. The [suggested system prompt](#suggested-system-prompt-for-coding-tasks) reinforces the early-call pattern. Add your own funnel-in sentence pointing at whichever planner tools your agent exposes.
#### Suggested system prompt for coding tasks
Without system-prompt steering, the executor tends to under-call the advisor in some domains, particularly coding tasks. For coding tasks where you want consistent advisor timing and around two to three calls for each task, prepend the following blocks to your executor system prompt before any other sentences that mention the advisor.
Timing guidance:
``` block
You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
```
How the executor should treat the advice (place directly after the timing block):
```python
Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.
If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.
```
#### Alternative system prompt for Haiku on coding workloads
Claude Haiku 4.5 applies the default advisor guidance conservatively. That keeps its call rate appropriately low on research and lookup workloads but gives up quality on coding workloads, where an early advisor consult reliably pays for itself. On an internal coding benchmark, a close variant of the following block (the read-only carve-out in the Hard rule was added after measurement) raised Haiku pass rates by roughly 7.5 percentage points over the built-in default.
Use this block in place of the earlier timing and advice blocks when your Haiku executor runs predominantly coding or write-task workloads:
```python
Consult a stronger reviewer who sees your full conversation transcript.
No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.
Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.
Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.
If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.
Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.
Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
```
**Caveat:** On an internal browse-comprehension benchmark (n = 1,266), a close variant of this block cost roughly 4 percentage points of accuracy relative to the built-in default. If your workload mixes coding with substantial lookup or retrieval, stay with the [suggested blocks](#suggested-system-prompt-for-coding-tasks), or gate the swap on a workload-type signal you already compute.
#### Increasing advisor calls on Opus executors
Opus executors typically call the advisor at an appropriate rate without additional prompting. If your Opus executor is under-calling on your workload, add the following checkpoint to your system prompt:
```python
Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)
Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
```
**Caveat:** In Anthropic's testing, a close variant of this block (the read-only carve-out in the Hard rule was added after measurement) raised pass rates on under-calling tasks by roughly 7 to 10 percentage points but caused Opus to over-call on tasks whose first action needs no planning. The net effect was roughly flat on a mixed workload. Only add it if you have observed Opus skipping the advisor on tasks where a consult would have helped. Do not add it as a default.
#### Trimming advisor output length
Advisor output is the advisor's largest cost driver, and the top-level `max_tokens` does not bound it. The advisor sees both your system prompt and your user messages as quoted context about the executor's task, so instructions that address the advisor directly are followed much more reliably than third-person descriptions. The most effective placement Anthropic tested is a line in the user message:
``` block
(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
```
This line can be prefixed programmatically by your agent framework before sending the request. The limit is a soft constraint. The advisor occasionally exceeds it, so ask for roughly 80 percent of your true ceiling.
In Anthropic's testing this line also increased how often the executor consults the advisor, but the net effect was still lower total cost (more consults, each shorter).
Pair this approach with the timing guidance in [Suggested system prompt for coding tasks](#suggested-system-prompt-for-coding-tasks) (or the [alternative Haiku block](#alternative-system-prompt-for-haiku-on-coding-workloads) if you swapped it in) for the strongest cost-versus-quality tradeoff. For a hard ceiling rather than a soft request, see [Capping advisor output](#capping-advisor-output).
### Capping advisor output
Set `max_tokens` on the tool definition to cap the advisor's total output (thinking plus text) per call:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"max_tokens": 2048,
}
]
```
The minimum value is 1024. Setting `max_tokens` above the advisor model's own output cap returns a 400 error. The cap applies to each advisor call independently and is not shared across calls in the same request.
This is not a hard truncation alone. The server also passes the advisor its remaining-token budget, so the advisor shapes its response to fit.
**Recommended starting point:** `max_tokens: 2048`. In Anthropic's testing on a hard reasoning benchmark (n = 40 per configuration), this reduced mean advisor output by roughly 7x compared with leaving the cap unset, with near-zero truncation and no detectable quality degradation. The minimum value of 1024 reduced output roughly 10x but truncated around 10 percent of calls. Accuracy differences across all configurations were within noise at this sample size. Validate on your own workload.
| `max_tokens` | Mean advisor output tokens | Calls truncated |
|--------------|----------------------------|-----------------|
| unset | ~4,200 to 5,900 | n/a |
| 2048 | ~630 to 840 | ~0% |
| 1024 | ~370 to 480 | ~10% |
Hard reasoning tasks elicit substantially longer advisor output than the [typical 1,400 to 1,800 tokens](#usage-and-billing) quoted earlier for lighter workloads. Use this table to size the savings ratio, not as a universal baseline for advisor output.
When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor sees the truncation in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"stop_reason": "max_tokens"
}
}
```
Check `output_tokens` on the corresponding `advisor_message` entry in `usage.iterations` to see how close each call came to its cap.
Compared with the [prompt-based approach](#trimming-advisor-output-length), `max_tokens` is a hard ceiling rather than a soft request. Use `max_tokens` when you need a guaranteed bound for cost or latency. Use the prompt-based approach (or both together) when you want to bias toward brevity without risking a mid-thought cut.
### Pairing with effort settings
For coding tasks, pairing a Sonnet executor at medium [effort](/docs/en/build-with-claude/effort) with an Opus advisor achieves intelligence comparable to Sonnet at default effort, at lower cost. For maximum intelligence, keep the executor at default effort.
### Cost control
- For conversation-level budgets, count advisor calls client-side. When you reach your cap, remove the advisor tool from `tools`; you do not need to strip `advisor_tool_result` blocks from your message history (see the note in [Multi-turn conversations](#multi-turn-conversations)).
- Enable `caching` only for conversations where you expect three or more advisor calls.
## Model compatibility
The executor model (the top-level `model` field) and the advisor model (the `model` field inside the tool definition) must form a valid pair. The advisor must be Claude Sonnet 4.6 or a more capable model, and it must be at least as capable as the executor. Models of equal capability (for example, Claude Opus 4.7 and Claude Opus 4.8) can advise each other.
[TABLE]
If you request an invalid pair, the API returns a `400 invalid_request_error` naming the unsupported combination.
### Platform availability
The advisor tool is available in beta on the Claude API and on [Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws). It is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry.
## Advisor on Claude Managed Agents
[Claude Managed Agents](/docs/en/managed-agents/overview) sessions support an advisor as well, configured as part of the agent rather than as a tool definition: add a `{"type": "advisor", "model": ...}` entry to the agent's multiagent roster, and the session's primary thread can consult that model mid-turn. The roster entry takes no `max_uses`, `max_tokens`, or `caching` options, and advice is delivered as thread events on the session's event stream rather than as `advisor_tool_result` blocks in the response. See [Give the session an advisor](/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
## Next steps
[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)
Store and retrieve information across conversations with a client-side memory directory.
[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)
Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, and domain filtering.
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
[Effort](/docs/en/build-with-claude/effort)
Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.
---
## Agents-Tools/agents-and-tools-tool-use-bash-tool-17760ed12d.md
# Bash tool
---
<Note>
This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/api-and-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
</Note>
The bash tool enables Claude to execute shell commands in a persistent bash session, allowing system operations, script execution, and command-line automation. Shell access is a foundational agent capability. On [Terminal-Bench 2.0](https://github.com/terminal-bench/terminal-bench), a benchmark that evaluates real-world terminal tasks using shell-only validation, Claude shows strong performance gains with access to a persistent bash session.
## Overview
The bash tool provides Claude with:
- Persistent bash session that maintains state
- Ability to run any shell command
- Access to environment variables and working directory
- Command chaining and scripting capabilities
For model support, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference).
## Use cases
- **Development workflows:** Run build commands, tests, and development tools
- **System automation:** Execute scripts, manage files, automate tasks
- **Data processing:** Process files, run analysis scripts, manage datasets
- **Environment setup:** Install packages, configure environments
## Quick start
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"tools": [
{
"type": "bash_20250124",
"name": "bash"
}
],
"messages": [
{
"role": "user",
"content": "List all Python files in the current directory."
}
]
}'
```
```bash CLI
ant messages create \
--model claude-opus-4-7 \
--max-tokens 1024 \
--tool '{type: bash_20250124, name: bash}' \
--message '{role: user, content: List all Python files in the current directory.}'
```
```python Python
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[
{"role": "user", "content": "List all Python files in the current directory."}
],
)
print(response)
```
</CodeGroup>
## How it works
The bash tool maintains a persistent session:
1. Claude determines what command to run
2. You execute the command in a bash shell
3. Return the output (stdout and stderr) to Claude
4. Session state persists between commands (environment variables, working directory)
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `command` | Yes* | The bash command to run |
| `restart` | No | Set to `true` to restart the bash session |
*Required unless using `restart`
<section title="Example usage">
Run a command:
```json
{
"command": "ls -la *.py"
}
```
Restart the session:
```json
{
"restart": true
}
```
</section>
## Example: Multi-step automation
Claude can chain commands to complete complex tasks:
```text
User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."
Claude's tool uses:
1. Install package
{"command": "pip install requests"}
2. Create script
{"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}
3. Run script
{"command": "python fetch_joke.py"}
```
The session maintains state between commands, so files created in step 2 are available in step 3.
## Implement the bash tool
The bash tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified.
<Steps>
<Step title="Set up a bash environment">
Create a persistent bash session that Claude can interact with:
```python hidelines={-2..-1}
import subprocess
import threading
import queue
class BashSession:
def __init__(self):
self.process = subprocess.Popen(
["/bin/bash"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
bufsize=0,
)
self.output_queue = queue.Queue()
self.error_queue = queue.Queue()
self._start_readers()
def _start_readers(self): ...
```
</Step>
<Step title="Handle command execution">
Create a function to execute commands and capture output:
```python hidelines={1..2,-1}
class BashSession:
def _read_output(self, timeout): ...
def execute_command(self, command):
# Send command to bash
self.process.stdin.write(command + "\n")
self.process.stdin.flush()
# Capture output with timeout
output = self._read_output(timeout=10)
return output
process = None
```
</Step>
<Step title="Process Claude's tool calls">
Extract and execute commands from Claude's responses:
```python hidelines={1..6}
from types import SimpleNamespace as _SN
response = _SN(
content=[_SN(type="tool_use", name="bash", input={"command": "ls"}, id="toolu_01")]
)
bash_session = _SN(restart=lambda: None, execute_command=lambda c: "output")
for content in response.content:
if content.type == "tool_use" and content.name == "bash":
if content.input.get("restart"):
bash_session.restart()
result = "Bash session restarted"
else:
command = content.input.get("command")
result = bash_session.execute_command(command)
# Return result to Claude
tool_result = {
"type": "tool_result",
"tool_use_id": content.id,
"content": result,
}
```
</Step>
<Step title="Implement safety measures">
Add validation and restrictions. Use an allowlist rather than a blocklist, since blocklists are easy to bypass. Reject shell operators so chained commands can't slip past the allowlist:
```python
import shlex
ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
def validate_command(command):
# Allow only commands from an explicit allowlist
try:
tokens = shlex.split(command)
except ValueError:
return False, "Could not parse command"
if not tokens:
return False, "Empty command"
executable = tokens[0]
if executable not in ALLOWED_COMMANDS:
return False, f"Command '{executable}' is not in the allowlist"
# Reject shell operators that would chain additional commands
for token in tokens[1:]:
if token in SHELL_OPERATORS or token.startswith(("$", "`")):
return False, f"Shell operator '{token}' is not allowed"
return True, None
```
This check is a first line of defense. For stronger isolation, run validated commands with `shell=False` and pass `shlex.split(command)` as the argument list, so the shell never interprets the string.
</Step>
</Steps>
### Handle errors
When implementing the bash tool, handle various error scenarios:
<section title="Command execution timeout">
If a command takes too long to execute:
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Command timed out after 30 seconds",
"is_error": true
}
]
}
```
</section>
<section title="Command not found">
If a command doesn't exist:
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: nonexistentcommand: command not found",
"is_error": true
}
]
}
```
</section>
<section title="Permission denied">
If there are permission issues:
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: /root/sensitive-file: Permission denied",
"is_error": true
}
]
}
```
</section>
### Follow implementation best practices
<section title="Use command timeouts">
Implement timeouts to prevent hanging commands:
```python hidelines={1..3}
import subprocess
def execute_with_timeout(command, timeout=30):
try:
result = subprocess.run(
command, shell=True, capture_output=True, text=True, timeout=timeout
)
return result.stdout + result.stderr
except subprocess.TimeoutExpired:
return f"Command timed out after {timeout} seconds"
```
</section>
<section title="Maintain session state">
Keep the bash session persistent to maintain environment variables and working directory:
```python
# Commands run in the same session maintain state
commands = [
"cd /tmp",
"echo 'Hello' > test.txt",
"cat test.txt", # This works because we're still in /tmp
]
```
</section>
<section title="Handle large outputs">
Truncate very large outputs to prevent token limit issues:
```python
def truncate_output(output, max_lines=100):
lines = output.split("\n")
if len(lines) > max_lines:
truncated = "\n".join(lines[:max_lines])
return f"{truncated}\n\n... Output truncated ({len(lines)} total lines) ..."
return output
```
</section>
<section title="Log all commands">
Keep an audit trail of executed commands:
```python
import logging
def log_command(command, output, user_id):
logging.info(f"User {user_id} executed: {command}")
logging.info(f"Output: {output[:200]}...") # Log first 200 chars
```
</section>
<section title="Sanitize outputs">
Remove sensitive information from command outputs:
```python
def sanitize_output(output):
# Remove potential secrets or credentials
import re
# Example: Remove AWS credentials
output = re.sub(r"aws_access_key_id\s*=\s*\S+", "aws_access_key_id=***", output)
output = re.sub(
r"aws_secret_access_key\s*=\s*\S+", "aws_secret_access_key=***", output
)
return output
```
</section>
## Security
<Warning>
The bash tool provides direct system access. Implement these essential safety measures:
- Running in isolated environments (Docker/VM)
- Implementing command filtering and allowlists
- Setting resource limits (CPU, memory, disk)
- Logging all executed commands
</Warning>
### Key recommendations
- Use `ulimit` to set resource constraints
- Filter dangerous commands (`sudo`, `rm -rf`, etc.)
- Run with minimal user permissions
- Monitor and log all command execution
## Pricing
The bash tool adds **245 input tokens** to your API calls.
Additional tokens are consumed by:
- Command outputs (stdout/stderr)
- Error messages
- Large file contents
See [tool use pricing](/docs/en/agents-and-tools/tool-use/overview#pricing) for complete pricing details.
## Common patterns
### Development workflows
- Running tests: `pytest && coverage report`
- Building projects: `npm install && npm run build`
- Git operations: `git status && git add . && git commit -m "message"`
#### Git-based checkpointing
Git serves as a structured recovery mechanism in long-running agent workflows, not just a way to save changes:
- **Capture a baseline:** Before any agent work begins, commit the current state. This is the known-good starting point.
- **Commit per feature:** Each completed feature gets its own commit. These serve as rollback points if something goes wrong later.
- **Reconstruct state at session start:** Read `git log` alongside a progress file to understand what has already been done and what comes next.
- **Revert on failure:** If work goes sideways, `git checkout` reverts to the last good commit instead of trying to debug a broken state.
### File operations
- Processing data: `wc -l *.csv && ls -lh *.csv`
- Searching files: `find . -name "*.py" | xargs grep "pattern"`
- Creating backups: `tar -czf backup.tar.gz ./data`
### System tasks
- Checking resources: `df -h && free -m`
- Process management: `ps aux | grep python`
- Environment setup: `export PATH=$PATH:/new/path && echo $PATH`
## Limitations
- **No interactive commands:** Cannot handle `vim`, `less`, or password prompts
- **No GUI applications:** Command-line only
- **Session scope:** Bash session state is client-side. The API is stateless. Your application is responsible for maintaining the shell session between turns.
- **Output limits:** Large outputs may be truncated
- **No streaming:** Results returned after completion
## Combining with other tools
The bash tool is most powerful when combined with the [text editor](/docs/en/agents-and-tools/tool-use/text-editor-tool) and other tools.
<Note>
If you're also using the [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool), Claude has access to two separate execution environments: your local bash session and Anthropic's sandboxed container. State is not shared between them. See [Using code execution with other execution tools](/docs/en/agents-and-tools/tool-use/code-execution-tool#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments.
</Note>
## Next steps
<CardGroup cols={2}>
<Card
title="Tool use overview"
icon="tool"
href="/docs/en/agents-and-tools/tool-use/overview"
>
Learn about tool use with Claude
</Card>
<Card
title="Text editor tool"
icon="file"
href="/docs/en/agents-and-tools/tool-use/text-editor-tool"
>
View and edit text files with Claude
</Card>
</CardGroup>
---
## Agents-Tools/agents-and-tools-tool-use-bash-tool-e6357c4a47.md
- [Managed Agents](/docs/en/managed-agents/overview)
- [Admin](/docs/en/manage-claude/admin-api)
- Resources
- [Best practices](/docs/en/about-claude/use-case-guides/overview)
- [Models & pricing](/docs/en/models/overview)
- [CLI, SDKs, and libraries](/docs/en/cli-sdks-libraries/overview)
- [Claude API skill](/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Release notes](/docs/en/release-notes/overview)
[API reference](/docs/en/api/overview)
[Console](/)[Log in](/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fbash-tool)
SearchCtrlK
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)[Authentication](/docs/en/manage-claude/authentication)
Building with Claude
[Features overview](/docs/en/build-with-claude/overview)[Using the Messages API](/docs/en/build-with-claude/working-with-messages)[Stop reasons and fallback](/docs/en/build-with-claude/handling-stop-reasons)[Refusals and fallback](/docs/en/build-with-claude/refusals-and-fallback)[Fallback credit](/docs/en/build-with-claude/fallback-credit)
Model capabilities
[Effort](/docs/en/build-with-claude/effort)[Task budgets (beta)](/docs/en/build-with-claude/task-budgets)[Fast mode (research preview)](/docs/en/build-with-claude/fast-mode)[Structured outputs](/docs/en/build-with-claude/structured-outputs)[Citations](/docs/en/build-with-claude/citations)[Streaming Messages](/docs/en/build-with-claude/streaming)[Batch processing](/docs/en/build-with-claude/batch-processing)[Search results](/docs/en/build-with-claude/search-results)[Streaming refusals](/docs/en/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)[Multilingual support](/docs/en/build-with-claude/multilingual-support)[Embeddings](/docs/en/build-with-claude/embeddings)
[Thinking](/docs/en/build-with-claude/thinking)
Tools
[Overview](/docs/en/agents-and-tools/tool-use/overview)[How tool use works](/docs/en/agents-and-tools/tool-use/how-tool-use-works)[Tutorial: Build a tool-using agent](/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent)[Define tools](/docs/en/agents-and-tools/tool-use/define-tools)[Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls)[Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use)[Tool Runner (SDK)](/docs/en/agents-and-tools/tool-use/tool-runner)[Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use)[Server tools](/docs/en/agents-and-tools/tool-use/server-tools)[Web search tool](/docs/en/agents-and-tools/tool-use/web-search-tool)[Web fetch tool](/docs/en/agents-and-tools/tool-use/web-fetch-tool)[Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)[Advisor tool](/docs/en/agents-and-tools/tool-use/advisor-tool)[Tool search tool](/docs/en/agents-and-tools/tool-use/tool-search-tool)[Memory tool](/docs/en/agents-and-tools/tool-use/memory-tool)[Bash tool](/docs/en/agents-and-tools/tool-use/bash-tool)[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)[Computer use tool](/docs/en/agents-and-tools/tool-use/computer-use-tool)[Browser use tool](/docs/en/agents-and-tools/tool-use/browser-use-tool)[Troubleshooting](/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use)
Tool infrastructure
[Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference)[Manage tool context](/docs/en/agents-and-tools/tool-use/manage-tool-context)[Tool combinations](/docs/en/agents-and-tools/tool-use/tool-combinations)[Tool use with prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)[Programmatic tool calling](/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)[Fine-grained tool streaming](/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)
Context management
[Context windows](/docs/en/build-with-claude/context-windows)[Context editing](/docs/en/build-with-claude/context-editing)[Prompt caching](/docs/en/build-with-claude/prompt-caching)[Mid-conversation system messages and tool changes](/docs/en/build-with-claude/mid-conversation-system-messages)[Build an orchestration mode](/docs/en/build-with-claude/mid-conversation-effort-example)[Cache diagnostics](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
[Compaction](/docs/en/build-with-claude/compaction)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
[Images and vision](/docs/en/build-with-claude/vision)
Skills
[Overview](/docs/en/agents-and-tools/agent-skills/overview)[Quickstart](/docs/en/agents-and-tools/agent-skills/quickstart)[Best practices](/docs/en/agents-and-tools/agent-skills/best-practices)[Skills for enterprise](/docs/en/agents-and-tools/agent-skills/enterprise)[Skills in the API](/docs/en/build-with-claude/skills-guide)
MCP
[Remote MCP servers](/docs/en/agents-and-tools/remote-mcp-servers)[MCP connector](/docs/en/agents-and-tools/mcp-connector)
[MCP tunnels](/docs/en/agents-and-tools/mcp-tunnels/overview)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](/docs/en/build-with-claude/claude-in-amazon-bedrock)[Amazon Bedrock (Opus 4.6 and earlier)](/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy)[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws)[Google Cloud](/docs/en/build-with-claude/claude-on-vertex-ai)[Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry)
[Console](/)
[Messages](/docs/en/intro)Tools
# Bash tool
Copy page
Let Claude request shell commands that your application runs in a persistent bash session and returns as tool results.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
The bash tool is a [client tool](/docs/en/agents-and-tools/tool-use/how-tool-use-works): Claude doesn't run commands itself. When you include the tool in a request, Claude replies with a `tool_use` block that names the command to run. Your application runs that command in a bash session it owns and returns the output in a `tool_result` block.
Your application keeps one bash process alive across tool calls, so state persists between commands. The working directory, environment variables, and any files a command creates are still there for the next command.
The current version of the tool is `bash_20250124`. For model support, beta headers, and the earlier version, see [Tool versions](#tool-versions). For all Anthropic-provided tools, see the [Tool reference](/docs/en/agents-and-tools/tool-use/tool-reference).
## Use cases
- **Development workflows:** Run build commands, tests, and development tools
- **System automation:** Execute scripts, manage files, automate tasks
- **Data processing:** Process files, run analysis scripts, manage datasets
- **Environment setup:** Install packages, configure environments
## Quick start
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[
{"role": "user", "content": "List all Python files in the current directory."}
],
)
print(response)
```
Claude responds with `stop_reason: "tool_use"` and a `tool_use` block that contains the command for your application to run:
Output
```python
{
"id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll list all Python files in the current directory for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "bash",
"input": {
"command": "ls *.py"
}
}
]
}
```
Run `input.command` in your bash session and send the output back as a `tool_result`. See [Implement the bash tool](#implement-the-bash-tool) for the round trip.
## How it works
Each tool call is one round trip between Claude and your application:
1. Claude returns a `tool_use` block containing the `command` to run.
2. Your application runs the command in its bash session.
3. Your application returns the command's output, stdout and stderr together, to Claude in a `tool_result` block.
4. Claude either requests another command in the same session or responds with text.
Claude can also return several `tool_use` blocks in one response. Run them in order in the same session and return all of the results in one `user` message. See [Parallel tool use](/docs/en/agents-and-tools/tool-use/parallel-tool-use).
The API is stateless. Nothing about your shell session travels between requests, so your application decides when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](/docs/en/agents-and-tools/tool-use/handle-tool-calls).
## Parameters
A bash tool definition has two required fields, `type` and `name`, and the `name` must be `bash`. The tool is schema-less: you don't provide an `input_schema`, because the schema is built into Claude's model and can't be modified. The following table lists the input fields Claude sets when it calls the tool.
| Parameter | Required | Description |
|-----------|----------|-------------------------------------------|
| `command` | Yes\* | The bash command to run |
| `restart` | No | Set to `true` to restart the bash session |
\*Required unless using `restart`
To handle `restart: true`, kill the shell process, start a new one, and return a `tool_result` that confirms the restart. A restarted session starts clean: the working directory, environment variables, and any running processes are gone.
### Example usage
Run a command:
```python
{
"command": "ls -la *.py"
}
```
Restart the session:
```python
{
"restart": true
}
```
## Tool versions
`bash_20250124` is the current version of the tool, and it requires no beta header. Every model from Claude Sonnet 3.7 ([retired](/docs/en/about-claude/model-deprecations)) onward accepts it, including all current Claude models.
The original `bash_20241022` version works only with the October 2024 Claude Sonnet 3.5 model ([retired](/docs/en/about-claude/model-deprecations)). Requests that use it need the `anthropic-beta: computer-use-2024-10-22` header, and the SDKs expose it only in their beta namespaces. New integrations should use `bash_20250124`.
## Example: Multistep automation
Claude can chain commands across tool calls to complete a multistep task:
``` inline-block
User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."
Claude's tool uses:
1. Install package
{"command": "pip install requests"}
2. Create script
{"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}
3. Run script
{"command": "python fetch_joke.py"}
```
The session maintains state between commands, so files created in step 2 are available in step 3.
## Implement the bash tool
Claude determines which command to run. Your application owns everything else: the shell process, the timeout, and the safety checks. The following steps show a minimal implementation.
1. 1
### Create a persistent bash session
Start one long-lived bash process and run every command inside it. Because a pipe to a live process never reports end-of-file, the session prints a unique sentinel line after each command to mark where that command's output ends:
Python
TypeScript
C#
Go
Java
PHP
Ruby
``` shiki
import subprocess
import uuid
class BashSession:
"""A bash process that stays alive between commands so state persists."""
def __init__(self):
self.process = subprocess.Popen(
["/bin/bash"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT, # interleave errors with output, in order
start_new_session=True, # own process group: a timeout can kill every child
text=True,
)
def execute_command(self, command):
"""Run a command in the session and return its output."""
sentinel = f"__CLAUDE_BASH_DONE_{uuid.uuid4().hex}__" # unique per call
self.process.stdin.write(f"{command}\necho {sentinel}\n")
self.process.stdin.flush()
output = []
for line in self.process.stdout:
if sentinel in line: # this command's output is complete
break
output.append(line)
return "".join(output)
def restart(self):
self.process.kill()
self.process.wait()
self.__init__()
bash_session = BashSession()
print(bash_session.execute_command("cd /tmp && pwd"))
print(bash_session.execute_command("pwd")) # still /tmp: the session kept its state
```
The session interleaves stderr with stdout, so error messages land where they happened. The example leaves out what a complete implementation also needs: a timeout that kills the shell and every process it started when a command hangs, then restarts the session. The [Use command timeouts](#follow-implementation-best-practices) best practice shows one way to add it.
2. 2
### Process Claude's tool calls
Extract and run commands from Claude's responses:
Python
TypeScript
C#
Go
Java
PHP
Ruby
``` shiki
tool_results = []
for content in response.content:
if content.type == "tool_use" and content.name == "bash":
if content.input.get("restart"):
bash_session.restart()
result = "Bash session restarted"
else:
command = content.input.get("command")
result = bash_session.execute_command(command)
# One tool_result per tool_use block, all returned in the next user message
tool_results.append(
{"type": "tool_result", "tool_use_id": content.id, "content": result}
)
```
3. 3
### Return the result to Claude
Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or finishes its answer:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
``` shiki
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[
{"role": "user", "content": "List all Python files in the current directory."},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "bash",
"input": {"command": "ls *.py"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "analysis.py\nprocess_data.py\n",
}
],
},
],
)
print(response.content)
```
Repeat the run-and-return cycle while `stop_reason` is `tool_use`. For the full loop, see [Handling results from client tools](/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools).
4. 4
### Implement safety measures
Add validation and restrictions. Use an allowlist rather than a blocklist: a blocklist misses any command it didn't anticipate. The example also rejects shell operators that appear as separate words:
Python
TypeScript
C#
Go
Java
PHP
Ruby
``` shiki
import shlex
ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
def validate_command(command):
# Allow only commands from an explicit allowlist
try:
tokens = shlex.split(command)
except ValueError:
return False, "Could not parse command"
if not tokens:
return False, "Empty command"
executable = tokens[0]
if executable not in ALLOWED_COMMANDS:
return False, f"Command '{executable}' is not in the allowlist"
# Reject shell operators written as separate words
for token in tokens[1:]:
if token in SHELL_OPERATORS or token.startswith(("$", "`")):
return False, f"Shell operator '{token}' is not allowed"
return True, None
```
This check is a tripwire for obvious mistakes, not an enforcement boundary. It rejects the spaced chaining (`&&`), pipes, and redirection that the other examples on this page use. It does not catch an operator glued to a word, such as `cat data.txt|grep x`, because the tokenizer keeps `data.txt|grep` inside one token. Decide which commands and operators your application allows. The real control is isolation: run the whole session inside a container or a virtual machine (see [Security](#security)).
### Handle errors
When a command fails or the session breaks, tell Claude what happened. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is_error](/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-errors-with-is-error).
### Command execution timeout
If a command takes too long to execute:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: command did not finish within 30 seconds",
"is_error": true
}
]
}
```
### Command not found
If a command doesn't exist:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: nonexistentcommand: command not found",
"is_error": true
}
]
}
```
### Permission denied
If there are permission issues:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: /root/sensitive-file: Permission denied",
"is_error": true
}
]
}
```
### Follow implementation best practices
### Use command timeouts
A command that never finishes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
import concurrent.futures
import os
import signal
def execute_with_timeout(session, command, timeout=30):
"""Run a command in the session, replacing the session if the command hangs."""
with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
future = pool.submit(session.execute_command, command)
try:
return future.result(timeout=timeout)
except concurrent.futures.TimeoutError:
# The group is the shell and every process the command started
os.killpg(session.process.pid, signal.SIGKILL)
session.restart()
return f"Error: command did not finish within {timeout} seconds"
```
The kill stops the hung command and everything it started. Return the message as an error `tool_result` (see [Handle errors](#handle-errors)), which marks the tool call as failed.
### Maintain session state
Keep the bash session persistent to maintain environment variables and working directory:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
# Commands run in the same session maintain state
commands = [
"cd /tmp",
"echo 'Hello' > test.txt",
"cat test.txt", # The session is still in /tmp
]
```
### Handle large outputs
Truncate large outputs to prevent token limit issues:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
def truncate_output(output, max_lines=100):
lines = output.split("\n")
if len(lines) > max_lines:
truncated = "\n".join(lines[:max_lines])
return f"{truncated}\n\n... Output truncated ({len(lines)} total lines) ..."
return output
```
### Log all commands
Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it finishes. A command that hangs or breaks the session still leaves a record:
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
import logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
def execute_and_log(session, command):
"""Run a command in the session and keep an audit record of it."""
logging.info("command=%r", command)
output = session.execute_command(command)
logging.info("output=%r", output[:200]) # first 200 characters
return output
```
The records go to `stderr` by default; point them at a file or your logging pipeline to keep them. Include whatever ties the record to the request in your application, such as the end user and the `tool_use_id`.
## Security
Your application runs whatever command Claude requests. Run the session in an isolated environment, such as a container or a virtual machine, as the least-privileged user that can do the work. Treat every command as untrusted input.
Beyond isolation, add these controls:
- Validate commands before running them, with an allowlist rather than a blocklist. See [Implement the bash tool](#implement-the-bash-tool).
- Set resource limits on the shell process (CPU, memory, and disk), for example with `ulimit`.
- Log every command and its output so you can audit what ran.
- Redact credentials and other secrets from output before returning it to Claude.
## Pricing
The bash tool definition adds the following input tokens to your request. This is in addition to the per-model [tool use system prompt](/docs/en/agents-and-tools/tool-use/overview#pricing) that applies whenever any tool is present.
| Model | Additional input tokens |
|-----------------------------------------------------|-------------------------|
| Claude Opus 5, Claude Opus 4.8, and Claude Opus 4.7 | 325 tokens |
| Claude Opus 4.6, Claude Sonnet 4.6, and earlier | 244 tokens |
Additional tokens are consumed by:
- Command outputs (stdout/stderr)
- Error messages
- Large file contents
See [tool use pricing](/docs/en/agents-and-tools/tool-use/overview#pricing) for complete pricing details.
## Common patterns
### Development workflows
- Running tests: `pytest && coverage report`
- Building projects: `npm install && npm run build`
- Git operations: `git status && git add . && git commit -m "message"`
For guidance on using git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#state-management-best-practices).
### File operations
- Processing data: `wc -l *.csv && ls -lh *.csv`
- Searching files: `find . -name "*.py" | xargs grep "pattern"`
- Creating backups: `tar -czf backup.tar.gz ./data`
### System tasks
- Checking resources: `df -h && free -m`
- Process management: `ps aux | grep python`
- Environment setup: `export PATH=$PATH:/new/path && echo $PATH`
## Limitations
- **No interactive commands:** The session can't run `vim`, `less`, password prompts, or any command that waits for input on stdin.
- **No GUI applications:** The session is command-line only.
- **Session scope:** Bash session state is client-side. Your application is responsible for maintaining the shell session between turns.
- **Output limits:** The API doesn't truncate tool results (an oversized request is rejected). Truncate large outputs in your application before returning them to Claude.
- **No streaming:** Output reaches Claude only when your application returns the `tool_result` in the next request.
## Combining with other tools
The bash tool pairs well with the [Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool): Claude edits a file with one tool and requests the command that runs it with the other.
If you're also using the [Code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool), Claude has access to two separate execution environments: your local bash session and Anthropic's sandboxed container. State is not shared between them. See [Using code execution with other execution tools](/docs/en/agents-and-tools/tool-use/code-execution-tool#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments.
## Next steps
[Text editor tool](/docs/en/agents-and-tools/tool-use/text-editor-tool)
View and modify text files to debug, fix, and improve code.
[Tool use with Claude](/docs/en/agents-and-tools/tool-use/overview)
Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
---
*Truncated: 1832 more documents not shown (size limit)*