llms.txt@04-API-Reference · git:20260802.073248b · 2026-08-02 · sha256 92512537cda1150a
llms.txt@04-API-Reference git:20260802.073248bF
Immutable. This exact content never changes and is served at /api/v1/blob/92512537cda1150a.
# API Reference
All documentation for API Reference.
---
## 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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Glossary
Best practices/Reference
# Glossary
These concepts are not unique to Anthropic’s language models, but this page presents a brief summary of key terms.
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
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 the [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 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/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
Models
[Models overview](/docs/en/about-claude/models/overview)[Model IDs and versioning](/docs/en/about-claude/models/model-ids-and-versions)[Choosing a model](/docs/en/about-claude/models/choosing-a-model)[Introducing Claude Fable 5 and Claude Mythos 5](/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5)[What's new in Claude Sonnet 5](/docs/en/about-claude/models/whats-new-sonnet-5)[What's new in Claude Opus 5](/docs/en/about-claude/models/whats-new-opus-5)[Upgrade between model versions](/docs/en/about-claude/models/migration-guide)[Model deprecations](/docs/en/about-claude/model-deprecations)[Model cards](/docs/en/resources/overview)[System prompts](/docs/en/release-notes/system-prompts)[Pricing](/docs/en/about-claude/pricing)
[](/login)
Models & pricing
Model deprecations
Models & pricing/Models
# Model deprecations
See which Claude models are active, deprecated, or retired, and find retirement dates and recommended replacements for models and API parameters.
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
[Claude Mythos Preview](https://anthropic.com/glasswing) (`claude-mythos-preview`) is deprecated. To migrate to [Claude Mythos 5](https://anthropic.com/glasswing) (`claude-mythos-5`), see the [migration guide](/docs/en/about-claude/models/migration-guide#migrating-from-claude-mythos-preview).
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 | Active | N/A | Not sooner than June 9, 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 | Deprecated | 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
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. Deprecated parameters remain in the SDK request types so existing code continues to type-check, but their behavior changes per model.
| 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-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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Content moderation
Best practices/Use cases
# 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.
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).
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
### You want both semantic understanding and quick decisions
### You need consistent policy decisions
### Your moderation policies are likely to change or evolve over time
### You require interpretable reasoning for your moderation decisions
### You need multilingual support without maintaining separate models
### You require multimodal support
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.
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/about-claude/models/overview#latest-models-comparison).
Content moderation cookbook
View a fully implemented code-based example of how to use Claude for content moderation.
Guardrails guide
Explore the guardrails guide for 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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Customer support agent
Best practices/Use cases
# Customer support agent
Build a customer support chatbot with Claude that answers product questions, stays on topic, and generates quotes through tool use.
Prerequisites
To follow this guide, you need:
- A Claude API key (set as the `ANTHROPIC_API_KEY` environment variable)
- Python 3.9 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
### Need for quick information synthesis
### 24/7 availability requirement
### Rapid scaling during peak periods
### Consistent brand voice
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
### Response relevance
### Response accuracy
### Citation provision relevance
### Topic adherence
### Content generation effectiveness
### Escalation efficiency
Here are criteria and benchmarks that can be used to evaluate the business impact of employing Claude for support:
### Sentiment maintenance
### Deflection rate
### Customer satisfaction score
### Average handle time
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 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 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"
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#building-evals-and-test-cases) 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
Give Claude access to your APIs so it can take action on behalf of customers.
Develop tests
Build evaluations to measure your support agent against the success criteria you defined.
Streaming
Stream responses so customers see answers as they generate.
Prompt engineering
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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Legal summarization
Best practices/Use cases
# 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 such as Claude to summarize legal documents:
### You want to review a high volume of documents efficiently and affordably
### You require automated extraction of key metadata
### You want to generate clear, concise, and standardized summaries
### You need precise citations for your summaries
### You want to streamline and expedite your legal research process
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
### Legal precision
### Conciseness
### Consistency
### Readability
### Bias and fairness
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", 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#building-evals-and-test-cases) 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
### BLEU scores
### Contextual embedding similarity
### LLM-based grading
### Human evaluation
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", 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
View a fully implemented code-based example of how to use Claude to summarize contracts.
Citations cookbook
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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Overview
Best practices/Use cases
# Guides to common use cases
Explore production guides for building common Claude use cases: ticket routing, customer support agents, content moderation, and legal summarization.
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
Best practices for using Claude to classify and route customer support tickets at scale.
Customer support agent
Build intelligent, context-aware chatbots with Claude to enhance customer support interactions.
Content moderation
Techniques and best practices for using Claude to perform content filtering and general content moderation.
Legal summarization
Summarize legal documents using Claude to extract key information and expedite research.
---
## 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/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
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)
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](/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-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)
[](/login)
Best practices
Ticket routing
Best practices/Use cases
# 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.
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
### Your classification categories are likely to change or evolve over time
### You need to handle complex, unstructured text inputs
### Your classification rules are based on semantic understanding
### You require interpretable reasoning for classification decisions
### You want to handle edge cases and ambiguous tickets more effectively
### You need multilingual support without maintaining separate models
------------------------------------------------------------------------
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
### Account management
### Product information
### User guidance
### Feedback
### Order-related
### Service request
### Security concerns
### Compliance and legal
### Emergency support
### Training and education
### Integration and API
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
### Adaptation speed
### Multilingual handling
### Edge case handling
### Bias mitigation
### Prompt efficiency
### Explainability score
Here are some common success criteria that may be useful regardless of whether an LLM is used:
### Routing accuracy
### Time-to-assignment
### Rerouting rate
### First-contact resolution rate
### Average handling time
### Customer satisfaction scores
### Escalation rate
### Agent productivity
### Self-service deflection rate
### Cost per ticket
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/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.
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,
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.
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,
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
```
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
### Claude prioritizes emotion over intent
### Multiple issues cause issue prioritization confusion
------------------------------------------------------------------------
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
Visit the classification cookbook for more example code and detailed eval guidance.
Claude Console
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Artifacts
# Artifacts
##### [Get Artifact Activity](/docs/en/api/admin/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
##### ModelsExpand Collapse
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 user_id / rbac_group_id) multiply the cube and paginate like the other analytics list endpoints.
data: array of object { artifact_type, artifacts_created_count, distinct_user_count, 6 more }
artifact_type: string
Canonical artifact MIME type (e.g. text/markdown, application/vnd.ant.react, image/svg+xml), or 'other'.
[](#artifact_usage.data.items.artifact_type)
artifacts_created_count: number
Number of artifacts created in this bucket on the requested day
[](#artifact_usage.data.items.artifacts_created_count)
distinct_user_count: number
Number of distinct users who created artifacts in this bucket on the requested day
[](#artifact_usage.data.items.distinct_user_count)
is_shared: boolean
Whether the artifacts in this bucket have ever been shared.
[](#artifact_usage.data.items.is_shared)
published_artifacts_created_count: number
Number of those artifacts that have been published
[](#artifact_usage.data.items.published_artifacts_created_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#artifact_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#artifact_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#artifact_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#artifact_usage.data.items.user_id)
[](#artifact_usage.data)
next_page: optional string
Cursor for the next page of a grouped query; always null for the ungrouped artifact-type cube, which is returned in full.
[](#artifact_usage.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#list.date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by: 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. 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.
[](#list.group_by)
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.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's next_page field. Only valid with group_by\[\] — the ungrouped cube is never paginated.
[](#list.page)
##### ReturnsExpand Collapse
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 user_id / rbac_group_id) multiply the cube and paginate like the other analytics list endpoints.
data: array of object { artifact_type, artifacts_created_count, distinct_user_count, 6 more }
artifact_type: string
Canonical artifact MIME type (e.g. text/markdown, application/vnd.ant.react, image/svg+xml), or 'other'.
[](#artifact_usage.data.items.artifact_type)
artifacts_created_count: number
Number of artifacts created in this bucket on the requested day
[](#artifact_usage.data.items.artifacts_created_count)
distinct_user_count: number
Number of distinct users who created artifacts in this bucket on the requested day
[](#artifact_usage.data.items.distinct_user_count)
is_shared: boolean
Whether the artifacts in this bucket have ever been shared.
[](#artifact_usage.data.items.is_shared)
published_artifacts_created_count: number
Number of those artifacts that have been published
[](#artifact_usage.data.items.published_artifacts_created_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#artifact_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#artifact_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#artifact_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#artifact_usage.data.items.user_id)
[](#artifact_usage.data)
next_page: optional string
Cursor for the next page of a grouped query; always null for the ungrouped artifact-type cube, which is returned in full.
[](#artifact_usage.next_page)
[](#artifact_usage)
Get Artifact Activity
```python
curl https://api.anthropic.com/v1/organizations/analytics/artifacts \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Analytics
# Analytics
##### [Get Activity Summaries](/docs/en/api/admin/analytics/retrieve_summaries)
GET/v1/organizations/analytics/summaries
##### ModelsExpand Collapse
ActivitySummary object { summaries }
Response for GET /v1/organizations/analytics/summaries.
summaries: array of object { assigned_seat_count, cowork_daily_active_user_count, cowork_monthly_active_user_count, 26 more }
assigned_seat_count: number
Number of seats currently assigned to members. Null when the response is scoped to an RBAC group — seat assignment is org-wide and has no per-group analogue.
[](#activity_summary.summaries.items.assigned_seat_count)
cowork_daily_active_user_count: number
Number of users with Cowork activity on the requested day
[](#activity_summary.summaries.items.cowork_daily_active_user_count)
cowork_monthly_active_user_count: number
Number of users with Cowork activity in the 30-day rolling window
[](#activity_summary.summaries.items.cowork_monthly_active_user_count)
cowork_weekly_active_user_count: number
Number of users with Cowork activity in the 7-day rolling window
[](#activity_summary.summaries.items.cowork_weekly_active_user_count)
daily_active_user_count: number
Number of users with token consumption on the requested day
[](#activity_summary.summaries.items.daily_active_user_count)
daily_adoption_rate: number
Percentage of assigned seats with activity on the requested day (DAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.daily_adoption_rate)
ending_at: string
End time in UTC of aggregation period (e.g. 2026-01-16T00:00
)
[](#activity_summary.summaries.items.ending_at)
monthly_active_user_count: number
Number of users with token consumption in the 30-day rolling window
[](#activity_summary.summaries.items.monthly_active_user_count)
monthly_adoption_rate: number
Percentage of assigned seats with activity in the 30-day rolling window (MAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.monthly_adoption_rate)
pending_invite_count: number
Number of pending invitations to join the organization. Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.pending_invite_count)
starting_at: string
Start time in UTC of aggregation period (e.g. 2026-01-15T00:00
)
[](#activity_summary.summaries.items.starting_at)
weekly_active_user_count: number
Number of users with token consumption in the 7-day rolling window
[](#activity_summary.summaries.items.weekly_active_user_count)
weekly_adoption_rate: number
Percentage of assigned seats with activity in the 7-day rolling window (WAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.weekly_adoption_rate)
chat_daily_active_user_count: optional number
Number of users with claude.ai (chat) activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_daily_active_user_count)
chat_monthly_active_user_count: optional number
Number of users with claude.ai (chat) activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_monthly_active_user_count)
chat_weekly_active_user_count: optional number
Number of users with claude.ai (chat) activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_weekly_active_user_count)
claude_code_daily_active_user_count: optional number
Number of users with Claude Code activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_daily_active_user_count)
claude_code_monthly_active_user_count: optional number
Number of users with Claude Code activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_monthly_active_user_count)
claude_code_weekly_active_user_count: optional number
Number of users with Claude Code activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_weekly_active_user_count)
claude_design_daily_active_user_count: optional number
Number of users with Claude Design activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_daily_active_user_count)
claude_design_monthly_active_user_count: optional number
Number of users with Claude Design activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_monthly_active_user_count)
claude_design_weekly_active_user_count: optional number
Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_weekly_active_user_count)
office_agent_daily_active_user_count: optional number
Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_daily_active_user_count)
office_agent_monthly_active_user_count: optional number
Number of users with Claude in Office activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_monthly_active_user_count)
office_agent_weekly_active_user_count: optional number
Number of users with Claude in Office activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_weekly_active_user_count)
science_daily_active_user_count: optional number
Number of users with Claude Science activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_daily_active_user_count)
science_entitled_user_count: optional number
Number of users with a Claude Science seat entitlement (per-seat RBAC) at the time of the daily snapshot. The funnel top; independent of the org-level Claude Science toggle. Null when the response is scoped to an RBAC group — entitlement is org-wide and has no per-group analogue. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_entitled_user_count)
science_monthly_active_user_count: optional number
Number of users with Claude Science activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_monthly_active_user_count)
science_weekly_active_user_count: optional number
Number of users with Claude Science activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_weekly_active_user_count)
[](#activity_summary.summaries)
[](#activity_summary)
AnalyticsUser object { id, email_address }
User identifier.
id: string
Tagged user identifier (e.g. user\_...)
[](#analytics_user.id)
email_address: string
Email address of the user
[](#analytics_user.email_address)
[](#analytics_user)
AnalyticsUserActor object { user_id, deleted, email, 2 more }
user_id: string
Tagged user ID.
[](#analytics_user_actor.user_id)
deleted: optional boolean
True if the account has been deleted. `name` is `"Deleted User"` and `email` is null in that case; the `user_id` is still populated for reconciliation.
[](#analytics_user_actor.deleted)
email: optional string
The user's email address. Null when unavailable or when the account has been deleted (check `deleted`).
[](#analytics_user_actor.email)
name: optional string
The user's name. Returns `"Deleted User"` when the account has been deleted (`deleted: true`). Null when unavailable.
[](#analytics_user_actor.name)
type: optional "user_actor"
[](#analytics_user_actor.type)
[](#analytics_user_actor)
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
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.
[](#connector_office_product_metrics.distinct_session_connector_used_count)
[](#connector_office_product_metrics)
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
[](#office_product_metrics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#office_product_metrics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#office_product_metrics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#office_product_metrics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#office_product_metrics.message_count)
skills_used_count: number
Number of skill invocations
[](#office_product_metrics.skills_used_count)
[](#office_product_metrics)
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
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.
[](#skill_office_product_metrics.distinct_session_skill_used_count)
[](#skill_office_product_metrics)
ToolActionCounts object { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#tool_action_counts.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#tool_action_counts.rejected_count)
[](#tool_action_counts)
#### AnalyticsUsage
##### [Get Token Usage Over Time](/docs/en/api/admin/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
##### [Get Per-User Token Usage](/docs/en/api/admin/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
#### AnalyticsCost
##### [Get Cost Over Time](/docs/en/api/admin/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
##### [Get Per-User Cost](/docs/en/api/admin/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
#### AnalyticsUsers
##### [List User Activity](/docs/en/api/admin/analytics/users/list)
GET/v1/organizations/analytics/users
#### AnalyticsSkills
##### [Get Skill Usage](/docs/en/api/admin/analytics/skills/list)
GET/v1/organizations/analytics/skills
#### AnalyticsConnectors
##### [Get Connector Usage](/docs/en/api/admin/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
#### AnalyticsChat Projects
##### [Get Chat Project Usage](/docs/en/api/admin/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
#### AnalyticsPlugins
##### [Get Plugin Usage](/docs/en/api/admin/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
#### AnalyticsArtifacts
##### [Get Artifact Activity](/docs/en/api/admin/analytics/artifacts/list)
GET/v1/organizations/analytics/artifacts
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Chat projects
# Chat Projects
##### [Get Chat Project Usage](/docs/en/api/admin/analytics/chat_projects/list)
GET/v1/organizations/analytics/apps/chat/projects
##### ModelsExpand Collapse
ChatProjectUsage object { data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
data: array of object { distinct_user_count, message_count, project_id, 8 more }
distinct_user_count: number
Number of distinct users who used the project on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#chat_project_usage.data.items.distinct_user_count)
message_count: number
Number of messages sent in the project on the requested day
[](#chat_project_usage.data.items.message_count)
project_id: string
Tagged project identifier (e.g. claude_proj\_...)
[](#chat_project_usage.data.items.project_id)
project_name: string
Name of the project
[](#chat_project_usage.data.items.project_name)
created_at: optional string
Project creation timestamp, RFC 3339. Null if the project was deleted before attribution was recorded.
[](#chat_project_usage.data.items.created_at)
created_by: optional [AnalyticsUser](/docs/en/api/admin/analytics#analytics_user) { id, email_address }
User identifier.
id: string
Tagged user identifier (e.g. user\_...)
[](#chat_project_usage.data.items.created_by%20%2B%20(resource)%20admin.analytics.id)
email_address: string
Email address of the user
[](#chat_project_usage.data.items.created_by%20%2B%20(resource)%20admin.analytics.email_address)
[](#chat_project_usage.data.items.created_by)
distinct_conversation_count: optional number
Number of distinct conversations in the project. Null on aggregated rows where a distinct count cannot be computed.
[](#chat_project_usage.data.items.distinct_conversation_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#chat_project_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#chat_project_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#chat_project_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#chat_project_usage.data.items.user_id)
[](#chat_project_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#chat_project_usage.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#list.date)
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.
[](#list.ending_date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by, e.g. group_by\[\]=rbac_group_id. Supported dimensions vary by endpoint; an unsupported dimension returns 400. Grouped responses paginate like ungrouped ones via next_page. 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.
[](#list.group_by)
limit: optional number
Number of results per page (1-1000, default 100).
[](#list.limit)
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"
[](#list.order%5B0%5D)
"desc"
[](#list.order%5B1%5D)
[](#list.order)
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).
[](#list.order_by)
page: optional string
Opaque cursor from a previous response's next_page field.
[](#list.page)
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.
[](#list.starting_date)
##### ReturnsExpand Collapse
ChatProjectUsage object { data, next_page }
Response for GET /v1/organizations/analytics/apps/chat/projects.
data: array of object { distinct_user_count, message_count, project_id, 8 more }
distinct_user_count: number
Number of distinct users who used the project on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#chat_project_usage.data.items.distinct_user_count)
message_count: number
Number of messages sent in the project on the requested day
[](#chat_project_usage.data.items.message_count)
project_id: string
Tagged project identifier (e.g. claude_proj\_...)
[](#chat_project_usage.data.items.project_id)
project_name: string
Name of the project
[](#chat_project_usage.data.items.project_name)
created_at: optional string
Project creation timestamp, RFC 3339. Null if the project was deleted before attribution was recorded.
[](#chat_project_usage.data.items.created_at)
created_by: optional [AnalyticsUser](/docs/en/api/admin/analytics#analytics_user) { id, email_address }
User identifier.
id: string
Tagged user identifier (e.g. user\_...)
[](#chat_project_usage.data.items.created_by%20%2B%20(resource)%20admin.analytics.id)
email_address: string
Email address of the user
[](#chat_project_usage.data.items.created_by%20%2B%20(resource)%20admin.analytics.email_address)
[](#chat_project_usage.data.items.created_by)
distinct_conversation_count: optional number
Number of distinct conversations in the project. Null on aggregated rows where a distinct count cannot be computed.
[](#chat_project_usage.data.items.distinct_conversation_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#chat_project_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#chat_project_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#chat_project_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#chat_project_usage.data.items.user_id)
[](#chat_project_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#chat_project_usage.next_page)
[](#chat_project_usage)
Get Chat Project Usage
```python
curl https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"distinct_user_count": 0,
"message_count": 0,
"project_id": "project_id",
"project_name": "project_name",
"created_at": "created_at",
"created_by": {
"id": "id",
"email_address": "email_address"
},
"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": "created_at",
"created_by": {
"id": "id",
"email_address": "email_address"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Connectors
# Connectors
##### [Get Connector Usage](/docs/en/api/admin/analytics/connectors/list)
GET/v1/organizations/analytics/connectors
##### ModelsExpand Collapse
ConnectorUsage object { data, next_page }
Response for GET /v1/organizations/analytics/connectors.
data: array of object { chat_metrics, claude_code_metrics, connector_name, 10 more }
chat_metrics: object { distinct_conversation_connector_used_count }
Claude.ai activity metrics for a single connector on a given day.
distinct_conversation_connector_used_count: number
Number of distinct conversations 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.
[](#connector_usage.data.items.chat_metrics.distinct_conversation_connector_used_count)
[](#connector_usage.data.items.chat_metrics)
claude_code_metrics: object { distinct_session_connector_used_count }
Claude Code activity metrics for a single connector on a given day.
distinct_session_connector_used_count: number
Number of distinct Claude Code 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.
[](#connector_usage.data.items.claude_code_metrics.distinct_session_connector_used_count)
[](#connector_usage.data.items.claude_code_metrics)
connector_name: string
Name of the connector
[](#connector_usage.data.items.connector_name)
cowork_metrics: object { distinct_session_connector_used_count }
Cowork activity metrics for a single connector on a given day.
distinct_session_connector_used_count: number
Number of distinct Cowork 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.
[](#connector_usage.data.items.cowork_metrics.distinct_session_connector_used_count)
[](#connector_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users who used the connector on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#connector_usage.data.items.distinct_user_count)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single connector on a given day, broken out by Office product.
excel: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.excel)
outlook: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.outlook)
powerpoint: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.powerpoint)
word: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.word)
[](#connector_usage.data.items.office_metrics)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#connector_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#connector_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#connector_usage.data.items.rbac_group_name)
read_call_count: optional number
Number of connector tool calls on the requested day whose trusted read-only annotation marked them read-only. Call count, not distinct users. Every call recorded on a classified surface lands in exactly one of read_call_count, write_call_count, or unclassified_call_count, so the three sum to the day's classified calls. Classification is forward-only per surface: claude.ai from 2026-06-01, Claude Code from 2026-05-30, Claude in Office from 2026-05-29, Cowork from 2026-06-02 (Cowork clients predating annotation forwarding land in unclassified_call_count). Null, never 0, when the value cannot be stated: the read/write split is not enabled for this organization, or the day predates 2026-05-29. For a date-range total, sum the per-day values, but treat a window that extends before 2026-05-29 as null rather than summing only its covered days — date-range rollup mode (starting_date/ending_date) applies both rules server-side.
[](#connector_usage.data.items.read_call_count)
unclassified_call_count: optional number
Number of connector tool calls on the requested day with no trusted read-only annotation — the annotation is optional in the MCP spec and is discarded when connector access controls are active, so unclassified calls are common. This field shows how much of the day's classified activity the read/write split actually covers. Call count, not distinct users. One of the three call-classification buckets; see read_call_count for the per-surface data-start dates, null conditions, and date-range guidance.
[](#connector_usage.data.items.unclassified_call_count)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#connector_usage.data.items.user_id)
write_call_count: optional number
Number of connector tool calls on the requested day whose trusted read-only annotation marked them not read-only. Call count, not distinct users. One of the three call-classification buckets; see read_call_count for the per-surface data-start dates, null conditions, and date-range guidance.
[](#connector_usage.data.items.write_call_count)
[](#connector_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#connector_usage.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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". Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#list.date)
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.
[](#list.ending_date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by, e.g. group_by\[\]=rbac_group_id. Supported dimensions vary by endpoint; an unsupported dimension returns 400. Grouped responses paginate like ungrouped ones via next_page. 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.
[](#list.group_by)
limit: optional number
Number of results per page (1-1000, default 100).
[](#list.limit)
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"
[](#list.order%5B0%5D)
"desc"
[](#list.order%5B1%5D)
[](#list.order)
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).
[](#list.order_by)
page: optional string
Opaque cursor from a previous response's next_page field.
[](#list.page)
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.
[](#list.starting_date)
##### ReturnsExpand Collapse
ConnectorUsage object { data, next_page }
Response for GET /v1/organizations/analytics/connectors.
data: array of object { chat_metrics, claude_code_metrics, connector_name, 10 more }
chat_metrics: object { distinct_conversation_connector_used_count }
Claude.ai activity metrics for a single connector on a given day.
distinct_conversation_connector_used_count: number
Number of distinct conversations 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.
[](#connector_usage.data.items.chat_metrics.distinct_conversation_connector_used_count)
[](#connector_usage.data.items.chat_metrics)
claude_code_metrics: object { distinct_session_connector_used_count }
Claude Code activity metrics for a single connector on a given day.
distinct_session_connector_used_count: number
Number of distinct Claude Code 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.
[](#connector_usage.data.items.claude_code_metrics.distinct_session_connector_used_count)
[](#connector_usage.data.items.claude_code_metrics)
connector_name: string
Name of the connector
[](#connector_usage.data.items.connector_name)
cowork_metrics: object { distinct_session_connector_used_count }
Cowork activity metrics for a single connector on a given day.
distinct_session_connector_used_count: number
Number of distinct Cowork 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.
[](#connector_usage.data.items.cowork_metrics.distinct_session_connector_used_count)
[](#connector_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users who used the connector on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#connector_usage.data.items.distinct_user_count)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single connector on a given day, broken out by Office product.
excel: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.excel)
outlook: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.outlook)
powerpoint: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.powerpoint)
word: [ConnectorOfficeProductMetrics](/docs/en/api/admin/analytics#connector_office_product_metrics) { 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
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.
[](#connector_usage.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_connector_used_count)
[](#connector_usage.data.items.office_metrics.word)
[](#connector_usage.data.items.office_metrics)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#connector_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#connector_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#connector_usage.data.items.rbac_group_name)
read_call_count: optional number
Number of connector tool calls on the requested day whose trusted read-only annotation marked them read-only. Call count, not distinct users. Every call recorded on a classified surface lands in exactly one of read_call_count, write_call_count, or unclassified_call_count, so the three sum to the day's classified calls. Classification is forward-only per surface: claude.ai from 2026-06-01, Claude Code from 2026-05-30, Claude in Office from 2026-05-29, Cowork from 2026-06-02 (Cowork clients predating annotation forwarding land in unclassified_call_count). Null, never 0, when the value cannot be stated: the read/write split is not enabled for this organization, or the day predates 2026-05-29. For a date-range total, sum the per-day values, but treat a window that extends before 2026-05-29 as null rather than summing only its covered days — date-range rollup mode (starting_date/ending_date) applies both rules server-side.
[](#connector_usage.data.items.read_call_count)
unclassified_call_count: optional number
Number of connector tool calls on the requested day with no trusted read-only annotation — the annotation is optional in the MCP spec and is discarded when connector access controls are active, so unclassified calls are common. This field shows how much of the day's classified activity the read/write split actually covers. Call count, not distinct users. One of the three call-classification buckets; see read_call_count for the per-surface data-start dates, null conditions, and date-range guidance.
[](#connector_usage.data.items.unclassified_call_count)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#connector_usage.data.items.user_id)
write_call_count: optional number
Number of connector tool calls on the requested day whose trusted read-only annotation marked them not read-only. Call count, not distinct users. One of the three call-classification buckets; see read_call_count for the per-surface data-start dates, null conditions, and date-range guidance.
[](#connector_usage.data.items.write_call_count)
[](#connector_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#connector_usage.next_page)
[](#connector_usage)
Get Connector Usage
```python
curl https://api.anthropic.com/v1/organizations/analytics/connectors \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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
}
},
"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
}
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Cost
# Cost
##### [Get Cost Over Time](/docs/en/api/admin/analytics/cost/list)
GET/v1/organizations/analytics/cost_report
##### [Get Per-User Cost](/docs/en/api/admin/analytics/cost/list_by_user)
GET/v1/organizations/analytics/user_cost_report
##### ModelsExpand Collapse
CostBucket object { data, data_refreshed_at, has_more, 2 more }
data: array of object { ending_at, results, starting_at }
ending_at: string
[](#cost_bucket.data.items.ending_at)
results: array of object { amount, context_window, cost_type, 9 more }
amount: string
Amount (post-discount, pre-credit) in fractional cents.
[](#cost_bucket.data.items.results.items.amount)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#cost_bucket.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#cost_bucket.data.items.results.items.context_window%5B1%5D)
[](#cost_bucket.data.items.results.items.context_window)
cost_type: "code_execution" or "tokens" or "web_search"
Cost component when `group_by[]=cost_type`; null otherwise (amount is the combined total).
One of the following:
"code_execution"
[](#cost_bucket.data.items.results.items.cost_type%5B0%5D)
"tokens"
[](#cost_bucket.data.items.results.items.cost_type%5B1%5D)
"web_search"
[](#cost_bucket.data.items.results.items.cost_type%5B2%5D)
[](#cost_bucket.data.items.results.items.cost_type)
currency: "USD"
[](#cost_bucket.data.items.results.items.currency)
inference_geo: "global" or "us"
One of the following:
"global"
[](#cost_bucket.data.items.results.items.inference_geo%5B0%5D)
"us"
[](#cost_bucket.data.items.results.items.inference_geo%5B1%5D)
[](#cost_bucket.data.items.results.items.inference_geo)
list_amount: string
List-price amount (pre-discount) in fractional cents.
[](#cost_bucket.data.items.results.items.list_amount)
model: string
[](#cost_bucket.data.items.results.items.model)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#cost_bucket.data.items.results.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#cost_bucket.data.items.results.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#cost_bucket.data.items.results.items.requests)
speed: "fast" or "standard"
One of the following:
"fast"
[](#cost_bucket.data.items.results.items.speed%5B0%5D)
"standard"
[](#cost_bucket.data.items.results.items.speed%5B1%5D)
[](#cost_bucket.data.items.results.items.speed)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Token type when `group_by[]=token_type` and `cost_type=tokens`; null otherwise.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B2%5D)
"output_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B4%5D)
[](#cost_bucket.data.items.results.items.token_type)
[](#cost_bucket.data.items.results)
starting_at: string
[](#cost_bucket.data.items.starting_at)
[](#cost_bucket.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#cost_bucket.data_refreshed_at)
has_more: boolean
[](#cost_bucket.has_more)
next_page: string
[](#cost_bucket.next_page)
organization_id: string
ID of the Organization.
[](#cost_bucket.organization_id)
[](#cost_bucket)
UserCost object { data, data_refreshed_at, has_more, 2 more }
data: array of object { actor, amount, context_window, 12 more }
actor: [AnalyticsUserActor](/docs/en/api/admin/analytics#analytics_user_actor) { user_id, deleted, email, 2 more }
user_id: string
Tagged user ID.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.user_id)
deleted: optional boolean
True if the account has been deleted. `name` is `"Deleted User"` and `email` is null in that case; the `user_id` is still populated for reconciliation.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.deleted)
email: optional string
The user's email address. Null when unavailable or when the account has been deleted (check `deleted`).
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.email)
name: optional string
The user's name. Returns `"Deleted User"` when the account has been deleted (`deleted: true`). Null when unavailable.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.name)
type: optional "user_actor"
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.type)
[](#user_cost.data.items.actor)
amount: string
Amount (post-discount, pre-credit) in fractional cents (minor units).
[](#user_cost.data.items.amount)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#user_cost.data.items.context_window%5B0%5D)
"200k-1M"
[](#user_cost.data.items.context_window%5B1%5D)
[](#user_cost.data.items.context_window)
cost_type: "code_execution" or "tokens" or "web_search"
Cost component breakdown; null when returning the combined total.
One of the following:
"code_execution"
[](#user_cost.data.items.cost_type%5B0%5D)
"tokens"
[](#user_cost.data.items.cost_type%5B1%5D)
"web_search"
[](#user_cost.data.items.cost_type%5B2%5D)
[](#user_cost.data.items.cost_type)
currency: "USD"
[](#user_cost.data.items.currency)
ending_at: string
[](#user_cost.data.items.ending_at)
inference_geo: "global" or "us"
One of the following:
"global"
[](#user_cost.data.items.inference_geo%5B0%5D)
"us"
[](#user_cost.data.items.inference_geo%5B1%5D)
[](#user_cost.data.items.inference_geo)
list_amount: string
List-price amount (pre-discount) in fractional cents.
[](#user_cost.data.items.list_amount)
model: string
[](#user_cost.data.items.model)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#user_cost.data.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#user_cost.data.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#user_cost.data.items.requests)
speed: "fast" or "standard"
One of the following:
"fast"
[](#user_cost.data.items.speed%5B0%5D)
"standard"
[](#user_cost.data.items.speed%5B1%5D)
[](#user_cost.data.items.speed)
starting_at: string
[](#user_cost.data.items.starting_at)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Token type when cost_type=tokens; null otherwise.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#user_cost.data.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#user_cost.data.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#user_cost.data.items.token_type%5B2%5D)
"output_tokens"
[](#user_cost.data.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#user_cost.data.items.token_type%5B4%5D)
[](#user_cost.data.items.token_type)
[](#user_cost.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#user_cost.data_refreshed_at)
has_more: boolean
[](#user_cost.has_more)
next_page: string
[](#user_cost.next_page)
organization_id: string
ID of the Organization.
[](#user_cost.organization_id)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
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
.
[](#list.starting_at)
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
One of the following:
"1d"
[](#list.bucket_width%5B0%5D)
"1h"
[](#list.bucket_width%5B1%5D)
"1m"
[](#list.bucket_width%5B2%5D)
[](#list.bucket_width)
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.
One of the following:
"0-200k"
[](#list.context_windows.items%5B0%5D)
"200k-1M"
[](#list.context_windows.items%5B1%5D)
[](#list.context_windows)
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.
[](#list.ending_at)
group_by: optional array of "context_window" or "cost_type" or "inference_geo" or 5 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.
One of the following:
"context_window"
[](#list.group_by.items%5B0%5D)
"cost_type"
[](#list.group_by.items%5B1%5D)
"inference_geo"
[](#list.group_by.items%5B2%5D)
"model"
[](#list.group_by.items%5B3%5D)
"product"
[](#list.group_by.items%5B4%5D)
"rbac_group_id"
[](#list.group_by.items%5B5%5D)
"speed"
[](#list.group_by.items%5B6%5D)
"token_type"
[](#list.group_by.items%5B7%5D)
[](#list.group_by)
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.
One of the following:
"global"
[](#list.inference_geos.items%5B0%5D)
"not_available"
[](#list.inference_geos.items%5B1%5D)
"us"
[](#list.inference_geos.items%5B2%5D)
[](#list.inference_geos)
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).
[](#list.limit)
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
[](#list.models)
page: optional string
Opaque cursor from a previous response's `next_page` field.
[](#list.page)
products: optional array of string
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it.
[](#list.products)
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.
[](#list.rbac_group_ids)
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
One of the following:
"fast"
[](#list.speeds.items%5B0%5D)
"standard"
[](#list.speeds.items%5B1%5D)
[](#list.speeds)
user_ids: optional array of string
Filter to specific users by tagged user ID.
[](#list.user_ids)
##### ReturnsExpand Collapse
CostBucket object { data, data_refreshed_at, has_more, 2 more }
data: array of object { ending_at, results, starting_at }
ending_at: string
[](#cost_bucket.data.items.ending_at)
results: array of object { amount, context_window, cost_type, 9 more }
amount: string
Amount (post-discount, pre-credit) in fractional cents.
[](#cost_bucket.data.items.results.items.amount)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#cost_bucket.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#cost_bucket.data.items.results.items.context_window%5B1%5D)
[](#cost_bucket.data.items.results.items.context_window)
cost_type: "code_execution" or "tokens" or "web_search"
Cost component when `group_by[]=cost_type`; null otherwise (amount is the combined total).
One of the following:
"code_execution"
[](#cost_bucket.data.items.results.items.cost_type%5B0%5D)
"tokens"
[](#cost_bucket.data.items.results.items.cost_type%5B1%5D)
"web_search"
[](#cost_bucket.data.items.results.items.cost_type%5B2%5D)
[](#cost_bucket.data.items.results.items.cost_type)
currency: "USD"
[](#cost_bucket.data.items.results.items.currency)
inference_geo: "global" or "us"
One of the following:
"global"
[](#cost_bucket.data.items.results.items.inference_geo%5B0%5D)
"us"
[](#cost_bucket.data.items.results.items.inference_geo%5B1%5D)
[](#cost_bucket.data.items.results.items.inference_geo)
list_amount: string
List-price amount (pre-discount) in fractional cents.
[](#cost_bucket.data.items.results.items.list_amount)
model: string
[](#cost_bucket.data.items.results.items.model)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#cost_bucket.data.items.results.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#cost_bucket.data.items.results.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#cost_bucket.data.items.results.items.requests)
speed: "fast" or "standard"
One of the following:
"fast"
[](#cost_bucket.data.items.results.items.speed%5B0%5D)
"standard"
[](#cost_bucket.data.items.results.items.speed%5B1%5D)
[](#cost_bucket.data.items.results.items.speed)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Token type when `group_by[]=token_type` and `cost_type=tokens`; null otherwise.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B2%5D)
"output_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#cost_bucket.data.items.results.items.token_type%5B4%5D)
[](#cost_bucket.data.items.results.items.token_type)
[](#cost_bucket.data.items.results)
starting_at: string
[](#cost_bucket.data.items.starting_at)
[](#cost_bucket.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#cost_bucket.data_refreshed_at)
has_more: boolean
[](#cost_bucket.has_more)
next_page: string
[](#cost_bucket.next_page)
organization_id: string
ID of the Organization.
[](#cost_bucket.organization_id)
[](#cost_bucket)
Get Cost Over Time
```python
curl https://api.anthropic.com/v1/organizations/analytics/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"ending_at": "2019-12-27T18:11:19.117Z",
"results": [
{
"amount": "amount",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "model",
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"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",
"context_window": "0-200k",
"cost_type": "code_execution",
"currency": "USD",
"inference_geo": "global",
"list_amount": "list_amount",
"model": "model",
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List by user
# 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 ParametersExpand Collapse
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
.
[](#list_by_user.starting_at)
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"
[](#list_by_user.bucket_width%5B0%5D)
"1h"
[](#list_by_user.bucket_width%5B1%5D)
"1m"
[](#list_by_user.bucket_width%5B2%5D)
[](#list_by_user.bucket_width)
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.
One of the following:
"0-200k"
[](#list_by_user.context_windows.items%5B0%5D)
"200k-1M"
[](#list_by_user.context_windows.items%5B1%5D)
[](#list_by_user.context_windows)
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.
[](#list_by_user.ending_at)
exclude_deleted_users: optional boolean
If true, omit rows for deleted accounts. Pages may return fewer than `limit` rows when deleted users were filtered.
[](#list_by_user.exclude_deleted_users)
group_by: optional array of "context_window" or "cost_type" or "inference_geo" or 5 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.
One of the following:
"context_window"
[](#list_by_user.group_by.items%5B0%5D)
"cost_type"
[](#list_by_user.group_by.items%5B1%5D)
"inference_geo"
[](#list_by_user.group_by.items%5B2%5D)
"model"
[](#list_by_user.group_by.items%5B3%5D)
"product"
[](#list_by_user.group_by.items%5B4%5D)
"rbac_group_id"
[](#list_by_user.group_by.items%5B5%5D)
"speed"
[](#list_by_user.group_by.items%5B6%5D)
"token_type"
[](#list_by_user.group_by.items%5B7%5D)
[](#list_by_user.group_by)
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.
One of the following:
"global"
[](#list_by_user.inference_geos.items%5B0%5D)
"not_available"
[](#list_by_user.inference_geos.items%5B1%5D)
"us"
[](#list_by_user.inference_geos.items%5B2%5D)
[](#list_by_user.inference_geos)
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.
[](#list_by_user.limit)
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
[](#list_by_user.models)
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
One of the following:
"asc"
[](#list_by_user.order%5B0%5D)
"desc"
[](#list_by_user.order%5B1%5D)
[](#list_by_user.order)
order_by: optional "amount" or "list_amount"
Metric to rank actors by. Defaults to `amount`.
One of the following:
"amount"
[](#list_by_user.order_by%5B0%5D)
"list_amount"
[](#list_by_user.order_by%5B1%5D)
[](#list_by_user.order_by)
page: optional string
Opaque cursor from a previous response's `next_page` field.
[](#list_by_user.page)
products: optional array of string
Product surfaces to include. Defaults to all products. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it.
[](#list_by_user.products)
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.
[](#list_by_user.rbac_group_ids)
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
One of the following:
"fast"
[](#list_by_user.speeds.items%5B0%5D)
"standard"
[](#list_by_user.speeds.items%5B1%5D)
[](#list_by_user.speeds)
user_ids: optional array of string
Filter to specific users by tagged user ID.
[](#list_by_user.user_ids)
##### ReturnsExpand Collapse
UserCost object { data, data_refreshed_at, has_more, 2 more }
data: array of object { actor, amount, context_window, 12 more }
actor: [AnalyticsUserActor](/docs/en/api/admin/analytics#analytics_user_actor) { user_id, deleted, email, 2 more }
user_id: string
Tagged user ID.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.user_id)
deleted: optional boolean
True if the account has been deleted. `name` is `"Deleted User"` and `email` is null in that case; the `user_id` is still populated for reconciliation.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.deleted)
email: optional string
The user's email address. Null when unavailable or when the account has been deleted (check `deleted`).
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.email)
name: optional string
The user's name. Returns `"Deleted User"` when the account has been deleted (`deleted: true`). Null when unavailable.
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.name)
type: optional "user_actor"
[](#user_cost.data.items.actor%20%2B%20(resource)%20admin.analytics.type)
[](#user_cost.data.items.actor)
amount: string
Amount (post-discount, pre-credit) in fractional cents (minor units).
[](#user_cost.data.items.amount)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#user_cost.data.items.context_window%5B0%5D)
"200k-1M"
[](#user_cost.data.items.context_window%5B1%5D)
[](#user_cost.data.items.context_window)
cost_type: "code_execution" or "tokens" or "web_search"
Cost component breakdown; null when returning the combined total.
One of the following:
"code_execution"
[](#user_cost.data.items.cost_type%5B0%5D)
"tokens"
[](#user_cost.data.items.cost_type%5B1%5D)
"web_search"
[](#user_cost.data.items.cost_type%5B2%5D)
[](#user_cost.data.items.cost_type)
currency: "USD"
[](#user_cost.data.items.currency)
ending_at: string
[](#user_cost.data.items.ending_at)
inference_geo: "global" or "us"
One of the following:
"global"
[](#user_cost.data.items.inference_geo%5B0%5D)
"us"
[](#user_cost.data.items.inference_geo%5B1%5D)
[](#user_cost.data.items.inference_geo)
list_amount: string
List-price amount (pre-discount) in fractional cents.
[](#user_cost.data.items.list_amount)
model: string
[](#user_cost.data.items.model)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#user_cost.data.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#user_cost.data.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. Null when `group_by` includes `cost_type` or `token_type` (the count has no per-component attribution; read it from the ungrouped response). For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#user_cost.data.items.requests)
speed: "fast" or "standard"
One of the following:
"fast"
[](#user_cost.data.items.speed%5B0%5D)
"standard"
[](#user_cost.data.items.speed%5B1%5D)
[](#user_cost.data.items.speed)
starting_at: string
[](#user_cost.data.items.starting_at)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Token type when cost_type=tokens; null otherwise.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#user_cost.data.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#user_cost.data.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#user_cost.data.items.token_type%5B2%5D)
"output_tokens"
[](#user_cost.data.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#user_cost.data.items.token_type%5B4%5D)
[](#user_cost.data.items.token_type)
[](#user_cost.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#user_cost.data_refreshed_at)
has_more: boolean
[](#user_cost.has_more)
next_page: string
[](#user_cost.next_page)
organization_id: string
ID of the Organization.
[](#user_cost.organization_id)
[](#user_cost)
Get Per-User Cost
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"actor": {
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor"
},
"amount": "41280.000000",
"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": "model",
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"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": {
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor"
},
"amount": "41280.000000",
"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": "model",
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Plugins
# Plugins
##### [Get Plugin Usage](/docs/en/api/admin/analytics/plugins/list)
GET/v1/organizations/analytics/plugins
##### ModelsExpand Collapse
PluginUsage object { data, next_page }
Response for GET /v1/organizations/analytics/plugins.
data: array of object { claude_code_metrics, cowork_metrics, distinct_user_count, 8 more }
claude_code_metrics: object { distinct_session_plugin_used_count }
Claude Code activity metrics for a single plugin on a given day.
distinct_session_plugin_used_count: number
Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
[](#plugin_usage.data.items.claude_code_metrics.distinct_session_plugin_used_count)
[](#plugin_usage.data.items.claude_code_metrics)
cowork_metrics: object { distinct_session_plugin_used_count }
Cowork activity metrics for a single plugin on a given day.
distinct_session_plugin_used_count: number
Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
[](#plugin_usage.data.items.cowork_metrics.distinct_session_plugin_used_count)
[](#plugin_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users with recorded install or invocation activity for the plugin on the requested day (install-only users count), or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#plugin_usage.data.items.distinct_user_count)
install_count: number
Number of distinct users who installed the plugin on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#plugin_usage.data.items.install_count)
invocation_count: number
Number of plugin invocations on the requested day
[](#plugin_usage.data.items.invocation_count)
plugin_name: string
Name of the plugin
[](#plugin_usage.data.items.plugin_name)
plugin_id: optional string
Stable plugin identifier when available (e.g. serena@claude-plugins-official). Null for third-party Claude Code plugins (redacted at the source) and Cowork slash commands that carry only a hashed id.
[](#plugin_usage.data.items.plugin_id)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#plugin_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#plugin_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#plugin_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#plugin_usage.data.items.user_id)
[](#plugin_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#plugin_usage.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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. Requires an API key with the `read:analytics` scope. `starting_date` / `ending_date` select range-rollup mode like /skills.
##### Query ParametersExpand Collapse
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.
[](#list.date)
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.
[](#list.ending_date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by, e.g. group_by\[\]=rbac_group_id. Supported dimensions vary by endpoint; an unsupported dimension returns 400. Grouped responses paginate like ungrouped ones via next_page. 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.
[](#list.group_by)
limit: optional number
Number of results per page (1-1000, default 100).
[](#list.limit)
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"
[](#list.order%5B0%5D)
"desc"
[](#list.order%5B1%5D)
[](#list.order)
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).
[](#list.order_by)
page: optional string
Opaque cursor from a previous response's next_page field.
[](#list.page)
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.
[](#list.starting_date)
##### ReturnsExpand Collapse
PluginUsage object { data, next_page }
Response for GET /v1/organizations/analytics/plugins.
data: array of object { claude_code_metrics, cowork_metrics, distinct_user_count, 8 more }
claude_code_metrics: object { distinct_session_plugin_used_count }
Claude Code activity metrics for a single plugin on a given day.
distinct_session_plugin_used_count: number
Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
[](#plugin_usage.data.items.claude_code_metrics.distinct_session_plugin_used_count)
[](#plugin_usage.data.items.claude_code_metrics)
cowork_metrics: object { distinct_session_plugin_used_count }
Cowork activity metrics for a single plugin on a given day.
distinct_session_plugin_used_count: number
Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
[](#plugin_usage.data.items.cowork_metrics.distinct_session_plugin_used_count)
[](#plugin_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users with recorded install or invocation activity for the plugin on the requested day (install-only users count), or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#plugin_usage.data.items.distinct_user_count)
install_count: number
Number of distinct users who installed the plugin on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
[](#plugin_usage.data.items.install_count)
invocation_count: number
Number of plugin invocations on the requested day
[](#plugin_usage.data.items.invocation_count)
plugin_name: string
Name of the plugin
[](#plugin_usage.data.items.plugin_name)
plugin_id: optional string
Stable plugin identifier when available (e.g. serena@claude-plugins-official). Null for third-party Claude Code plugins (redacted at the source) and Cowork slash commands that carry only a hashed id.
[](#plugin_usage.data.items.plugin_id)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#plugin_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#plugin_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#plugin_usage.data.items.rbac_group_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#plugin_usage.data.items.user_id)
[](#plugin_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#plugin_usage.next_page)
[](#plugin_usage)
Get Plugin Usage
```python
curl https://api.anthropic.com/v1/organizations/analytics/plugins \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve summaries
# Get Activity Summaries
GET/v1/organizations/analytics/summaries
Get organization-wide activity summaries for a date range.
Returns one entry per day in \[starting_date, ending_date). 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. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#retrieve_summaries.starting_date)
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.
[](#retrieve_summaries.ending_date)
filter: optional array of string
Filters as 'dimension
'. 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.
[](#retrieve_summaries.filter)
##### ReturnsExpand Collapse
ActivitySummary object { summaries }
Response for GET /v1/organizations/analytics/summaries.
summaries: array of object { assigned_seat_count, cowork_daily_active_user_count, cowork_monthly_active_user_count, 26 more }
assigned_seat_count: number
Number of seats currently assigned to members. Null when the response is scoped to an RBAC group — seat assignment is org-wide and has no per-group analogue.
[](#activity_summary.summaries.items.assigned_seat_count)
cowork_daily_active_user_count: number
Number of users with Cowork activity on the requested day
[](#activity_summary.summaries.items.cowork_daily_active_user_count)
cowork_monthly_active_user_count: number
Number of users with Cowork activity in the 30-day rolling window
[](#activity_summary.summaries.items.cowork_monthly_active_user_count)
cowork_weekly_active_user_count: number
Number of users with Cowork activity in the 7-day rolling window
[](#activity_summary.summaries.items.cowork_weekly_active_user_count)
daily_active_user_count: number
Number of users with token consumption on the requested day
[](#activity_summary.summaries.items.daily_active_user_count)
daily_adoption_rate: number
Percentage of assigned seats with activity on the requested day (DAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.daily_adoption_rate)
ending_at: string
End time in UTC of aggregation period (e.g. 2026-01-16T00:00
)
[](#activity_summary.summaries.items.ending_at)
monthly_active_user_count: number
Number of users with token consumption in the 30-day rolling window
[](#activity_summary.summaries.items.monthly_active_user_count)
monthly_adoption_rate: number
Percentage of assigned seats with activity in the 30-day rolling window (MAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.monthly_adoption_rate)
pending_invite_count: number
Number of pending invitations to join the organization. Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.pending_invite_count)
starting_at: string
Start time in UTC of aggregation period (e.g. 2026-01-15T00:00
)
[](#activity_summary.summaries.items.starting_at)
weekly_active_user_count: number
Number of users with token consumption in the 7-day rolling window
[](#activity_summary.summaries.items.weekly_active_user_count)
weekly_adoption_rate: number
Percentage of assigned seats with activity in the 7-day rolling window (WAU / assigned_seat_count \* 100). Null when the response is scoped to an RBAC group.
[](#activity_summary.summaries.items.weekly_adoption_rate)
chat_daily_active_user_count: optional number
Number of users with claude.ai (chat) activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_daily_active_user_count)
chat_monthly_active_user_count: optional number
Number of users with claude.ai (chat) activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_monthly_active_user_count)
chat_weekly_active_user_count: optional number
Number of users with claude.ai (chat) activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.chat_weekly_active_user_count)
claude_code_daily_active_user_count: optional number
Number of users with Claude Code activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_daily_active_user_count)
claude_code_monthly_active_user_count: optional number
Number of users with Claude Code activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_monthly_active_user_count)
claude_code_weekly_active_user_count: optional number
Number of users with Claude Code activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_code_weekly_active_user_count)
claude_design_daily_active_user_count: optional number
Number of users with Claude Design activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_daily_active_user_count)
claude_design_monthly_active_user_count: optional number
Number of users with Claude Design activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_monthly_active_user_count)
claude_design_weekly_active_user_count: optional number
Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.claude_design_weekly_active_user_count)
office_agent_daily_active_user_count: optional number
Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_daily_active_user_count)
office_agent_monthly_active_user_count: optional number
Number of users with Claude in Office activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_monthly_active_user_count)
office_agent_weekly_active_user_count: optional number
Number of users with Claude in Office activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.office_agent_weekly_active_user_count)
science_daily_active_user_count: optional number
Number of users with Claude Science activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_daily_active_user_count)
science_entitled_user_count: optional number
Number of users with a Claude Science seat entitlement (per-seat RBAC) at the time of the daily snapshot. The funnel top; independent of the org-level Claude Science toggle. Null when the response is scoped to an RBAC group — entitlement is org-wide and has no per-group analogue. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_entitled_user_count)
science_monthly_active_user_count: optional number
Number of users with Claude Science activity in the 30-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_monthly_active_user_count)
science_weekly_active_user_count: optional number
Number of users with Claude Science activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
[](#activity_summary.summaries.items.science_weekly_active_user_count)
[](#activity_summary.summaries)
[](#activity_summary)
Get Activity Summaries
```python
curl https://api.anthropic.com/v1/organizations/analytics/summaries \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": "ending_at",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "starting_at",
"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": "ending_at",
"monthly_active_user_count": 0,
"monthly_adoption_rate": 0,
"pending_invite_count": 0,
"starting_at": "starting_at",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Skills
# Skills
##### [Get Skill Usage](/docs/en/api/admin/analytics/skills/list)
GET/v1/organizations/analytics/skills
##### ModelsExpand Collapse
SkillUsage object { data, next_page }
Response for GET /v1/organizations/analytics/skills.
data: array of object { chat_metrics, claude_code_metrics, cowork_metrics, 14 more }
chat_metrics: object { distinct_conversation_skill_used_count }
Claude.ai activity metrics for a single skill on a given day.
distinct_conversation_skill_used_count: number
Number of distinct conversations 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.
[](#skill_usage.data.items.chat_metrics.distinct_conversation_skill_used_count)
[](#skill_usage.data.items.chat_metrics)
claude_code_metrics: object { distinct_session_skill_used_count }
Claude Code activity metrics for a single skill on a given day.
distinct_session_skill_used_count: number
Number of distinct Claude Code 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.
[](#skill_usage.data.items.claude_code_metrics.distinct_session_skill_used_count)
[](#skill_usage.data.items.claude_code_metrics)
cowork_metrics: object { distinct_session_skill_used_count }
Cowork activity metrics for a single skill on a given day.
distinct_session_skill_used_count: number
Number of distinct Cowork 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.
[](#skill_usage.data.items.cowork_metrics.distinct_session_skill_used_count)
[](#skill_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users who used the skill on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. 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.
[](#skill_usage.data.items.distinct_user_count)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single skill on a given day, broken out by Office product.
excel: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.excel)
outlook: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.outlook)
powerpoint: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.powerpoint)
word: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.word)
[](#skill_usage.data.items.office_metrics)
skill_name: string
Name of the skill
[](#skill_usage.data.items.skill_name)
attributed_list_price: optional string
List-price (rate-card) value of the member requests attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD), from Claude Code, Cowork, and Office Agent request-level attribution — the value of requests that INVOLVED the skill, not the skill's incremental cost. Unlike estimated_overage_spend this reflects usage value regardless of how it was funded — seat-covered usage counts — but it is undiscounted and does NOT tie to billed spend or the organization's spend reporting. claude.ai chat usage carries no request-level attribution and contributes nothing: the field is null on chat product rows and on office_agent product cuts dated before 2026-06-18 (the Office Agent attribution data-start), and on ungrouped rows it covers the Claude Code + Cowork + Office Agent share only (null when no attributable usage exists). Also null under the same conditions as estimated_overage_spend (spend reporting not enabled for this organization, office_agent product cuts before the 2026-06-18 data-start). "0" means attributable usage existed but none was attributed to this skill. Addable across days: date-range rollup mode returns the window's sum. On group_by\[\] and filter\[\] shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts.
[](#skill_usage.data.items.attributed_list_price)
currency: optional "USD"
Currency for this row's monetary fields (estimated_overage_spend and attributed_list_price), as an uppercase ISO-4217 code. Always "USD" when either amount is populated; null whenever both amounts are null.
[](#skill_usage.data.items.currency)
enable_count: optional number
Distinct accounts that enabled this skill on the requested day (claude.ai only — the skill analog of plugin install_count). The count is org-wide: null when enable reporting is not enabled for this organization, or when the request scopes to user_id / rbac_group_id / product via group_by\[\] or filter\[\] (an org-wide count would be misleading on per-cut rows). A distinct count, not an event count: summing across days double-counts members who enable the skill on more than one day, so it is also null in date-range rollup mode (starting_date/ending_date).
[](#skill_usage.data.items.enable_count)
estimated_overage_spend: optional string
Estimated OVERAGE spend attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD; "1250" is \$12.50, fractional cents possible) — an allocation of each member's daily post-discount, pre-credit metered overage spend (the same cost basis as the organization's spend reporting and the Cost & Usage API, so per-skill figures are directly comparable; spend with no skill attribution — including any member-day without skill invocations — is not represented, so skill rows sum to at most those totals) across the skills the member used. Overage only: usage covered by included seat allowances bills nothing and allocates \$0 here — see attributed_list_price for the funding-independent usage-value companion. Claude Code, Cowork, and Office Agent spend use request-level skill attribution; claude.ai chat spend is approximated proportionally to skill-invoking messages. An estimate, not a billing number — and the cost of the requests/messages that INVOLVED the skill, not the skill's incremental cost (the same request would still have cost something without the skill active). "0" means no overage spend was attributed; null when spend reporting is not enabled for this organization, on office_agent product cuts dated before 2026-06-18 (the Office Agent attribution data-start). Addable across days: date-range rollup mode (starting_date/ending_date) returns the window's sum. With group_by\[\]=user_id each row carries the user's own attributed spend. On group_by\[\] and filter\[\] shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts.
[](#skill_usage.data.items.estimated_overage_spend)
invocation_count: optional number
Total number of times this skill was invoked on the requested day (the skill analog of plugin invocation_count). Unlike distinct_user_count — which answers '# of users' — this is the true '# of uses'. 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. Null when invocation reporting is not enabled for this organization. Sum across a date range for total uses in the window — date-range rollup mode (starting_date/ending_date) returns this sum directly.
[](#skill_usage.data.items.invocation_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#skill_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#skill_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#skill_usage.data.items.rbac_group_name)
share_status: optional string
Skill share status (claude.ai only): one of 'private', 'organization', or 'public'. Null for skills used only in Claude Code or Office (no per-skill share-status concept) and when share-status reporting is not yet available for the organization. Filterable via filter\[\]=share_status:\<value\>.
[](#skill_usage.data.items.share_status)
skill_display_name: optional string
Human-readable display name for rows whose skill_name is an opaque skill id (user/organization skill types — user-defined names are withheld from the analytics pipeline). Only organization-shared skills resolve; the literal 'unknown' bucket row also gets a fixed 'Unknown skill' label. Null for private (user-defined) skills — their names are not disclosed to analytics-key holders — and null when skill_name is already a display name, when the skill was deleted, or when display-name resolution is not enabled for this organization.
[](#skill_usage.data.items.skill_display_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#skill_usage.data.items.user_id)
[](#skill_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#skill_usage.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#list.date)
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.
[](#list.ending_date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by, e.g. group_by\[\]=rbac_group_id. Supported dimensions vary by endpoint; an unsupported dimension returns 400. Grouped responses paginate like ungrouped ones via next_page. 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.
[](#list.group_by)
limit: optional number
Number of results per page (1-1000, default 100).
[](#list.limit)
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"
[](#list.order%5B0%5D)
"desc"
[](#list.order%5B1%5D)
[](#list.order)
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).
[](#list.order_by)
page: optional string
Opaque cursor from a previous response's next_page field.
[](#list.page)
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.
[](#list.starting_date)
##### ReturnsExpand Collapse
SkillUsage object { data, next_page }
Response for GET /v1/organizations/analytics/skills.
data: array of object { chat_metrics, claude_code_metrics, cowork_metrics, 14 more }
chat_metrics: object { distinct_conversation_skill_used_count }
Claude.ai activity metrics for a single skill on a given day.
distinct_conversation_skill_used_count: number
Number of distinct conversations 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.
[](#skill_usage.data.items.chat_metrics.distinct_conversation_skill_used_count)
[](#skill_usage.data.items.chat_metrics)
claude_code_metrics: object { distinct_session_skill_used_count }
Claude Code activity metrics for a single skill on a given day.
distinct_session_skill_used_count: number
Number of distinct Claude Code 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.
[](#skill_usage.data.items.claude_code_metrics.distinct_session_skill_used_count)
[](#skill_usage.data.items.claude_code_metrics)
cowork_metrics: object { distinct_session_skill_used_count }
Cowork activity metrics for a single skill on a given day.
distinct_session_skill_used_count: number
Number of distinct Cowork 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.
[](#skill_usage.data.items.cowork_metrics.distinct_session_skill_used_count)
[](#skill_usage.data.items.cowork_metrics)
distinct_user_count: number
Number of distinct users who used the skill on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values. 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.
[](#skill_usage.data.items.distinct_user_count)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single skill on a given day, broken out by Office product.
excel: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.excel)
outlook: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.outlook)
powerpoint: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.powerpoint)
word: [SkillOfficeProductMetrics](/docs/en/api/admin/analytics#skill_office_product_metrics) { 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
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.
[](#skill_usage.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_skill_used_count)
[](#skill_usage.data.items.office_metrics.word)
[](#skill_usage.data.items.office_metrics)
skill_name: string
Name of the skill
[](#skill_usage.data.items.skill_name)
attributed_list_price: optional string
List-price (rate-card) value of the member requests attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD), from Claude Code, Cowork, and Office Agent request-level attribution — the value of requests that INVOLVED the skill, not the skill's incremental cost. Unlike estimated_overage_spend this reflects usage value regardless of how it was funded — seat-covered usage counts — but it is undiscounted and does NOT tie to billed spend or the organization's spend reporting. claude.ai chat usage carries no request-level attribution and contributes nothing: the field is null on chat product rows and on office_agent product cuts dated before 2026-06-18 (the Office Agent attribution data-start), and on ungrouped rows it covers the Claude Code + Cowork + Office Agent share only (null when no attributable usage exists). Also null under the same conditions as estimated_overage_spend (spend reporting not enabled for this organization, office_agent product cuts before the 2026-06-18 data-start). "0" means attributable usage existed but none was attributed to this skill. Addable across days: date-range rollup mode returns the window's sum. On group_by\[\] and filter\[\] shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts.
[](#skill_usage.data.items.attributed_list_price)
currency: optional "USD"
Currency for this row's monetary fields (estimated_overage_spend and attributed_list_price), as an uppercase ISO-4217 code. Always "USD" when either amount is populated; null whenever both amounts are null.
[](#skill_usage.data.items.currency)
enable_count: optional number
Distinct accounts that enabled this skill on the requested day (claude.ai only — the skill analog of plugin install_count). The count is org-wide: null when enable reporting is not enabled for this organization, or when the request scopes to user_id / rbac_group_id / product via group_by\[\] or filter\[\] (an org-wide count would be misleading on per-cut rows). A distinct count, not an event count: summing across days double-counts members who enable the skill on more than one day, so it is also null in date-range rollup mode (starting_date/ending_date).
[](#skill_usage.data.items.enable_count)
estimated_overage_spend: optional string
Estimated OVERAGE spend attributed to this skill, as a decimal string in the minor unit of `currency` (cents for USD; "1250" is \$12.50, fractional cents possible) — an allocation of each member's daily post-discount, pre-credit metered overage spend (the same cost basis as the organization's spend reporting and the Cost & Usage API, so per-skill figures are directly comparable; spend with no skill attribution — including any member-day without skill invocations — is not represented, so skill rows sum to at most those totals) across the skills the member used. Overage only: usage covered by included seat allowances bills nothing and allocates \$0 here — see attributed_list_price for the funding-independent usage-value companion. Claude Code, Cowork, and Office Agent spend use request-level skill attribution; claude.ai chat spend is approximated proportionally to skill-invoking messages. An estimate, not a billing number — and the cost of the requests/messages that INVOLVED the skill, not the skill's incremental cost (the same request would still have cost something without the skill active). "0" means no overage spend was attributed; null when spend reporting is not enabled for this organization, on office_agent product cuts dated before 2026-06-18 (the Office Agent attribution data-start). Addable across days: date-range rollup mode (starting_date/ending_date) returns the window's sum. With group_by\[\]=user_id each row carries the user's own attributed spend. On group_by\[\] and filter\[\] shapes both amounts can total below the ungrouped value for the same skill over the same date or range: spend attributed to a member–skill pair with no counted usage on that day is excluded from those cuts.
[](#skill_usage.data.items.estimated_overage_spend)
invocation_count: optional number
Total number of times this skill was invoked on the requested day (the skill analog of plugin invocation_count). Unlike distinct_user_count — which answers '# of users' — this is the true '# of uses'. 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. Null when invocation reporting is not enabled for this organization. Sum across a date range for total uses in the window — date-range rollup mode (starting_date/ending_date) returns this sum directly.
[](#skill_usage.data.items.invocation_count)
product: optional string
Product that produced this row's activity: one of chat, claude_code, cowork, or office_agent (the canonical Cost & Usage product naming; an office_agent row's per-surface breakdown is in its office_metrics). On /plugins only cowork and claude_code occur (the only surfaces with plugin attribution); /artifacts and /apps/chat/projects do not support the product dimension (a product group_by\[\] or filter\[\] there is rejected). Present only when the request grouped by product.
[](#skill_usage.data.items.product)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#skill_usage.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#skill_usage.data.items.rbac_group_name)
share_status: optional string
Skill share status (claude.ai only): one of 'private', 'organization', or 'public'. Null for skills used only in Claude Code or Office (no per-skill share-status concept) and when share-status reporting is not yet available for the organization. Filterable via filter\[\]=share_status:\<value\>.
[](#skill_usage.data.items.share_status)
skill_display_name: optional string
Human-readable display name for rows whose skill_name is an opaque skill id (user/organization skill types — user-defined names are withheld from the analytics pipeline). Only organization-shared skills resolve; the literal 'unknown' bucket row also gets a fixed 'Unknown skill' label. Null for private (user-defined) skills — their names are not disclosed to analytics-key holders — and null when skill_name is already a display name, when the skill was deleted, or when display-name resolution is not enabled for this organization.
[](#skill_usage.data.items.skill_display_name)
user_id: optional string
Tagged user identifier (e.g. user\_...). Present only when the request grouped by user_id.
[](#skill_usage.data.items.user_id)
[](#skill_usage.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#skill_usage.next_page)
[](#skill_usage)
Get Skill Usage
```python
curl https://api.anthropic.com/v1/organizations/analytics/skills \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": "share_status",
"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": "share_status",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Usage
# Usage
##### [Get Token Usage Over Time](/docs/en/api/admin/analytics/usage/list)
GET/v1/organizations/analytics/usage_report
##### [Get Per-User Token Usage](/docs/en/api/admin/analytics/usage/list_by_user)
GET/v1/organizations/analytics/user_usage_report
##### ModelsExpand Collapse
UsageBucket object { data, data_refreshed_at, has_more, 2 more }
data: array of object { ending_at, results, starting_at }
ending_at: string
[](#usage_bucket.data.items.ending_at)
results: array of object { cache_creation, cache_read_input_tokens, context_window, 9 more }
cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }
ephemeral_1h_input_tokens: number
The number of input tokens used to create the 1 hour cache entry.
[](#usage_bucket.data.items.results.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#usage_bucket.data.items.results.items.cache_creation.ephemeral_5m_input_tokens)
[](#usage_bucket.data.items.results.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#usage_bucket.data.items.results.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#usage_bucket.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#usage_bucket.data.items.results.items.context_window%5B1%5D)
[](#usage_bucket.data.items.results.items.context_window)
inference_geo: "global" or "us"
One of the following:
"global"
[](#usage_bucket.data.items.results.items.inference_geo%5B0%5D)
"us"
[](#usage_bucket.data.items.results.items.inference_geo%5B1%5D)
[](#usage_bucket.data.items.results.items.inference_geo)
model: string
[](#usage_bucket.data.items.results.items.model)
output_tokens: number
The number of output tokens generated.
[](#usage_bucket.data.items.results.items.output_tokens)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#usage_bucket.data.items.results.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#usage_bucket.data.items.results.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#usage_bucket.data.items.results.items.requests)
server_tool_use: object { web_search_requests }
web_search_requests: number
The number of web search requests made.
[](#usage_bucket.data.items.results.items.server_tool_use.web_search_requests)
[](#usage_bucket.data.items.results.items.server_tool_use)
speed: "fast" or "standard"
One of the following:
"fast"
[](#usage_bucket.data.items.results.items.speed%5B0%5D)
"standard"
[](#usage_bucket.data.items.results.items.speed%5B1%5D)
[](#usage_bucket.data.items.results.items.speed)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#usage_bucket.data.items.results.items.uncached_input_tokens)
[](#usage_bucket.data.items.results)
starting_at: string
[](#usage_bucket.data.items.starting_at)
[](#usage_bucket.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#usage_bucket.data_refreshed_at)
has_more: boolean
[](#usage_bucket.has_more)
next_page: string
[](#usage_bucket.next_page)
organization_id: string
ID of the Organization.
[](#usage_bucket.organization_id)
[](#usage_bucket)
UserUsage object { data, data_refreshed_at, has_more, 2 more }
data: array of object { actor, cache_creation, cache_read_input_tokens, 13 more }
actor: [AnalyticsUserActor](/docs/en/api/admin/analytics#analytics_user_actor) { user_id, deleted, email, 2 more }
user_id: string
Tagged user ID.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.user_id)
deleted: optional boolean
True if the account has been deleted. `name` is `"Deleted User"` and `email` is null in that case; the `user_id` is still populated for reconciliation.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.deleted)
email: optional string
The user's email address. Null when unavailable or when the account has been deleted (check `deleted`).
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.email)
name: optional string
The user's name. Returns `"Deleted User"` when the account has been deleted (`deleted: true`). Null when unavailable.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.name)
type: optional "user_actor"
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.type)
[](#user_usage.data.items.actor)
cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }
ephemeral_1h_input_tokens: number
The number of input tokens used to create the 1 hour cache entry.
[](#user_usage.data.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#user_usage.data.items.cache_creation.ephemeral_5m_input_tokens)
[](#user_usage.data.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#user_usage.data.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#user_usage.data.items.context_window%5B0%5D)
"200k-1M"
[](#user_usage.data.items.context_window%5B1%5D)
[](#user_usage.data.items.context_window)
ending_at: string
[](#user_usage.data.items.ending_at)
inference_geo: "global" or "us"
One of the following:
"global"
[](#user_usage.data.items.inference_geo%5B0%5D)
"us"
[](#user_usage.data.items.inference_geo%5B1%5D)
[](#user_usage.data.items.inference_geo)
model: string
[](#user_usage.data.items.model)
output_tokens: number
The number of output tokens generated.
[](#user_usage.data.items.output_tokens)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#user_usage.data.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#user_usage.data.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#user_usage.data.items.requests)
server_tool_use: object { web_search_requests }
web_search_requests: number
The number of web search requests made.
[](#user_usage.data.items.server_tool_use.web_search_requests)
[](#user_usage.data.items.server_tool_use)
speed: "fast" or "standard"
One of the following:
"fast"
[](#user_usage.data.items.speed%5B0%5D)
"standard"
[](#user_usage.data.items.speed%5B1%5D)
[](#user_usage.data.items.speed)
starting_at: string
[](#user_usage.data.items.starting_at)
total_tokens: number
Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.
[](#user_usage.data.items.total_tokens)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#user_usage.data.items.uncached_input_tokens)
[](#user_usage.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#user_usage.data_refreshed_at)
has_more: boolean
[](#user_usage.has_more)
next_page: string
[](#user_usage.next_page)
organization_id: string
ID of the Organization.
[](#user_usage.organization_id)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
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
.
[](#list.starting_at)
bucket_width: optional "1d" or "1h" or "1m"
Time bucket granularity.
One of the following:
"1d"
[](#list.bucket_width%5B0%5D)
"1h"
[](#list.bucket_width%5B1%5D)
"1m"
[](#list.bucket_width%5B2%5D)
[](#list.bucket_width)
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.
One of the following:
"0-200k"
[](#list.context_windows.items%5B0%5D)
"200k-1M"
[](#list.context_windows.items%5B1%5D)
[](#list.context_windows)
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.
[](#list.ending_at)
group_by: optional array of "context_window" or "inference_geo" or "model" or 3 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.
One of the following:
"context_window"
[](#list.group_by.items%5B0%5D)
"inference_geo"
[](#list.group_by.items%5B1%5D)
"model"
[](#list.group_by.items%5B2%5D)
"product"
[](#list.group_by.items%5B3%5D)
"rbac_group_id"
[](#list.group_by.items%5B4%5D)
"speed"
[](#list.group_by.items%5B5%5D)
[](#list.group_by)
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.
One of the following:
"global"
[](#list.inference_geos.items%5B0%5D)
"not_available"
[](#list.inference_geos.items%5B1%5D)
"us"
[](#list.inference_geos.items%5B2%5D)
[](#list.inference_geos)
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).
[](#list.limit)
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
[](#list.models)
page: optional string
Opaque cursor from a previous response's `next_page` field.
[](#list.page)
products: optional array of string
Product surfaces to include. Defaults to all products. Use `group_by[]=product` to break out per-product values. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it.
[](#list.products)
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.
[](#list.rbac_group_ids)
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
One of the following:
"fast"
[](#list.speeds.items%5B0%5D)
"standard"
[](#list.speeds.items%5B1%5D)
[](#list.speeds)
user_ids: optional array of string
Filter to specific users by tagged user ID.
[](#list.user_ids)
##### ReturnsExpand Collapse
UsageBucket object { data, data_refreshed_at, has_more, 2 more }
data: array of object { ending_at, results, starting_at }
ending_at: string
[](#usage_bucket.data.items.ending_at)
results: array of object { cache_creation, cache_read_input_tokens, context_window, 9 more }
cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }
ephemeral_1h_input_tokens: number
The number of input tokens used to create the 1 hour cache entry.
[](#usage_bucket.data.items.results.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#usage_bucket.data.items.results.items.cache_creation.ephemeral_5m_input_tokens)
[](#usage_bucket.data.items.results.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#usage_bucket.data.items.results.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#usage_bucket.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#usage_bucket.data.items.results.items.context_window%5B1%5D)
[](#usage_bucket.data.items.results.items.context_window)
inference_geo: "global" or "us"
One of the following:
"global"
[](#usage_bucket.data.items.results.items.inference_geo%5B0%5D)
"us"
[](#usage_bucket.data.items.results.items.inference_geo%5B1%5D)
[](#usage_bucket.data.items.results.items.inference_geo)
model: string
[](#usage_bucket.data.items.results.items.model)
output_tokens: number
The number of output tokens generated.
[](#usage_bucket.data.items.results.items.output_tokens)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#usage_bucket.data.items.results.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#usage_bucket.data.items.results.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#usage_bucket.data.items.results.items.requests)
server_tool_use: object { web_search_requests }
web_search_requests: number
The number of web search requests made.
[](#usage_bucket.data.items.results.items.server_tool_use.web_search_requests)
[](#usage_bucket.data.items.results.items.server_tool_use)
speed: "fast" or "standard"
One of the following:
"fast"
[](#usage_bucket.data.items.results.items.speed%5B0%5D)
"standard"
[](#usage_bucket.data.items.results.items.speed%5B1%5D)
[](#usage_bucket.data.items.results.items.speed)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#usage_bucket.data.items.results.items.uncached_input_tokens)
[](#usage_bucket.data.items.results)
starting_at: string
[](#usage_bucket.data.items.starting_at)
[](#usage_bucket.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Buckets beyond this watermark are incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#usage_bucket.data_refreshed_at)
has_more: boolean
[](#usage_bucket.has_more)
next_page: string
[](#usage_bucket.next_page)
organization_id: string
ID of the Organization.
[](#usage_bucket.organization_id)
[](#usage_bucket)
Get Token Usage Over Time
```python
curl https://api.anthropic.com/v1/organizations/analytics/usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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,
"context_window": "0-200k",
"inference_geo": "global",
"model": "model",
"output_tokens": 0,
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"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,
"context_window": "0-200k",
"inference_geo": "global",
"model": "model",
"output_tokens": 0,
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 0,
"server_tool_use": {
"web_search_requests": 10
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List by user
# 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 ParametersExpand Collapse
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
.
[](#list_by_user.starting_at)
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"
[](#list_by_user.bucket_width%5B0%5D)
"1h"
[](#list_by_user.bucket_width%5B1%5D)
"1m"
[](#list_by_user.bucket_width%5B2%5D)
[](#list_by_user.bucket_width)
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.
One of the following:
"0-200k"
[](#list_by_user.context_windows.items%5B0%5D)
"200k-1M"
[](#list_by_user.context_windows.items%5B1%5D)
[](#list_by_user.context_windows)
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.
[](#list_by_user.ending_at)
exclude_deleted_users: optional boolean
If true, omit rows for deleted accounts. Pages may return fewer than `limit` rows when deleted users were filtered.
[](#list_by_user.exclude_deleted_users)
group_by: optional array of "context_window" or "inference_geo" or "model" or 3 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.
One of the following:
"context_window"
[](#list_by_user.group_by.items%5B0%5D)
"inference_geo"
[](#list_by_user.group_by.items%5B1%5D)
"model"
[](#list_by_user.group_by.items%5B2%5D)
"product"
[](#list_by_user.group_by.items%5B3%5D)
"rbac_group_id"
[](#list_by_user.group_by.items%5B4%5D)
"speed"
[](#list_by_user.group_by.items%5B5%5D)
[](#list_by_user.group_by)
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.
One of the following:
"global"
[](#list_by_user.inference_geos.items%5B0%5D)
"not_available"
[](#list_by_user.inference_geos.items%5B1%5D)
"us"
[](#list_by_user.inference_geos.items%5B2%5D)
[](#list_by_user.inference_geos)
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.
[](#list_by_user.limit)
models: optional array of string
Models to include. Defaults to all models. Use `group_by[]=model` to break out per-model values.
[](#list_by_user.models)
order: optional "asc" or "desc"
Sort direction. Defaults to `desc`.
One of the following:
"asc"
[](#list_by_user.order%5B0%5D)
"desc"
[](#list_by_user.order%5B1%5D)
[](#list_by_user.order)
order_by: optional "output_tokens" or "requests" or "total_tokens" or "uncached_input_tokens"
Metric to rank actors by. Defaults to `total_tokens`.
One of the following:
"output_tokens"
[](#list_by_user.order_by%5B0%5D)
"requests"
[](#list_by_user.order_by%5B1%5D)
"total_tokens"
[](#list_by_user.order_by%5B2%5D)
"uncached_input_tokens"
[](#list_by_user.order_by%5B3%5D)
[](#list_by_user.order_by)
page: optional string
Opaque cursor from a previous response's `next_page` field.
[](#list_by_user.page)
products: optional array of string
Product surfaces to include. Defaults to all products. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it.
[](#list_by_user.products)
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.
[](#list_by_user.rbac_group_ids)
speeds: optional array of "fast" or "standard"
Filter to fast or standard inference mode. Use `group_by[]=speed` to break out per-mode values.
One of the following:
"fast"
[](#list_by_user.speeds.items%5B0%5D)
"standard"
[](#list_by_user.speeds.items%5B1%5D)
[](#list_by_user.speeds)
user_ids: optional array of string
Filter to specific users by tagged user ID.
[](#list_by_user.user_ids)
##### ReturnsExpand Collapse
UserUsage object { data, data_refreshed_at, has_more, 2 more }
data: array of object { actor, cache_creation, cache_read_input_tokens, 13 more }
actor: [AnalyticsUserActor](/docs/en/api/admin/analytics#analytics_user_actor) { user_id, deleted, email, 2 more }
user_id: string
Tagged user ID.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.user_id)
deleted: optional boolean
True if the account has been deleted. `name` is `"Deleted User"` and `email` is null in that case; the `user_id` is still populated for reconciliation.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.deleted)
email: optional string
The user's email address. Null when unavailable or when the account has been deleted (check `deleted`).
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.email)
name: optional string
The user's name. Returns `"Deleted User"` when the account has been deleted (`deleted: true`). Null when unavailable.
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.name)
type: optional "user_actor"
[](#user_usage.data.items.actor%20%2B%20(resource)%20admin.analytics.type)
[](#user_usage.data.items.actor)
cache_creation: object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }
ephemeral_1h_input_tokens: number
The number of input tokens used to create the 1 hour cache entry.
[](#user_usage.data.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#user_usage.data.items.cache_creation.ephemeral_5m_input_tokens)
[](#user_usage.data.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#user_usage.data.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
One of the following:
"0-200k"
[](#user_usage.data.items.context_window%5B0%5D)
"200k-1M"
[](#user_usage.data.items.context_window%5B1%5D)
[](#user_usage.data.items.context_window)
ending_at: string
[](#user_usage.data.items.ending_at)
inference_geo: "global" or "us"
One of the following:
"global"
[](#user_usage.data.items.inference_geo%5B0%5D)
"us"
[](#user_usage.data.items.inference_geo%5B1%5D)
[](#user_usage.data.items.inference_geo)
model: string
[](#user_usage.data.items.model)
output_tokens: number
The number of output tokens generated.
[](#user_usage.data.items.output_tokens)
product: string
Product surface that produced the usage or cost. Null unless product is in group_by\[\]; it can also be null on grouped rows whose usage cannot be attributed to a known surface. Values include "chat", "claude_code", "cowork", "office_agent", "claude_in_chrome", "claude_design", and "claude-in-slack". "claude-in-slack" (with hyphens) is Claude Tag, the Claude product in Slack. A similarly spelled legacy value (underscores instead of hyphens) identifies the retiring v1 Slack chat bot and appears only for organizations that used it. Some unattributed usage is reported as "other".
[](#user_usage.data.items.product)
rbac_group_id: string
RBAC group (team) the usage is attributed to, in the public tagged `rbac_group_...` spelling — the same spelling the activity resources use for this key, so the same team has ONE id across resources and it round-trips as an `rbac_group_ids[]` filter value. Populated only when `rbac_group_id` is in `group_by[]`. Any-membership semantics: a user in several groups contributes their full usage to each of those groups' rows, so the named-group rows overlap and their sum can exceed the org total. A null value is the single unassigned row: users in no group on that (UTC) day. For the true org total, run the same query with no group_by.
[](#user_usage.data.items.rbac_group_id)
requests: number
Number of API requests in this row's scope. For sandbox / code-execution events, this counts execution spans rather than HTTP requests (these rows surface with `product: null`).
[](#user_usage.data.items.requests)
server_tool_use: object { web_search_requests }
web_search_requests: number
The number of web search requests made.
[](#user_usage.data.items.server_tool_use.web_search_requests)
[](#user_usage.data.items.server_tool_use)
speed: "fast" or "standard"
One of the following:
"fast"
[](#user_usage.data.items.speed%5B0%5D)
"standard"
[](#user_usage.data.items.speed%5B1%5D)
[](#user_usage.data.items.speed)
starting_at: string
[](#user_usage.data.items.starting_at)
total_tokens: number
Total token count across all token types. This is the value the default order_by='total_tokens' sorts on.
[](#user_usage.data.items.total_tokens)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#user_usage.data.items.uncached_input_tokens)
[](#user_usage.data)
data_refreshed_at: string
RFC 3339 timestamp of the export this response was served from. Data beyond this watermark is incomplete; for stable results, set `ending_at` to this value or earlier. Data is typically refreshed every 4 hours but not final until about 30 days after the usage date (late-arriving events, reconciliation adjustments).
[](#user_usage.data_refreshed_at)
has_more: boolean
[](#user_usage.has_more)
next_page: string
[](#user_usage.next_page)
organization_id: string
ID of the Organization.
[](#user_usage.organization_id)
[](#user_usage)
Get Per-User Token Usage
```python
curl https://api.anthropic.com/v1/organizations/analytics/user_usage_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"actor": {
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "model",
"output_tokens": 891000,
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"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": {
"user_id": "user_01AbCdEfGhIjKlMnOpQrSt",
"deleted": true,
"email": "jane@example.com",
"name": "Jane Smith",
"type": "user_actor"
},
"cache_creation": {
"ephemeral_1h_input_tokens": 1000,
"ephemeral_5m_input_tokens": 500
},
"cache_read_input_tokens": 3200000,
"context_window": "0-200k",
"ending_at": "2019-12-27T18:11:19.117Z",
"inference_geo": "global",
"model": "model",
"output_tokens": 891000,
"product": "product",
"rbac_group_id": "rbac_group_012rppKaSVsmTo6NqRDXQXNF",
"requests": 128,
"server_tool_use": {
"web_search_requests": 10
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Users
# Users
##### [List User Activity](/docs/en/api/admin/analytics/users/list)
GET/v1/organizations/analytics/users
##### ModelsExpand Collapse
UserActivity object { data, next_page }
Response for GET /v1/organizations/analytics/users.
data: array of object { chat_metrics, claude_code_metrics, cowork_metrics, 9 more }
chat_metrics: object { connectors_used_count, distinct_artifacts_created_count, distinct_connectors_used_count, 9 more }
Claude.ai activity metrics for a single user on a given day.
connectors_used_count: number
Number of MCP connector invocations.
[](#user_activity.data.items.chat_metrics.connectors_used_count)
distinct_artifacts_created_count: number
Number of distinct artifacts created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.chat_metrics.distinct_artifacts_created_count)
distinct_connectors_used_count: number
Distinct claude.ai connectors this user used. Excludes calls whose connector could not be identified and all calls from organizations with zero data retention. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_connectors_used_count)
distinct_conversation_count: number
Number of distinct conversations the user participated in. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_conversation_count)
distinct_files_uploaded_count: number
Number of distinct files uploaded. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_files_uploaded_count)
distinct_projects_created_count: number
Number of distinct projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.chat_metrics.distinct_projects_created_count)
distinct_projects_used_count: number
Number of distinct projects used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_projects_used_count)
distinct_shared_artifacts_viewed_count: number
Number of distinct shared artifacts the user viewed. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_shared_artifacts_viewed_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.chat_metrics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.chat_metrics.message_count)
shared_conversations_viewed_count: number
Number of times the user opened a shared conversation in a project
[](#user_activity.data.items.chat_metrics.shared_conversations_viewed_count)
thinking_message_count: number
Number of messages that used extended thinking
[](#user_activity.data.items.chat_metrics.thinking_message_count)
[](#user_activity.data.items.chat_metrics)
claude_code_metrics: object { core_metrics, tool_actions }
Claude Code activity metrics for a single user on a given day.
core_metrics: object { commit_count, distinct_session_count, lines_of_code, pull_request_count }
Core Claude Code activity metrics for a single user on a given day.
commit_count: number
Number of commits made via Claude Code
[](#user_activity.data.items.claude_code_metrics.core_metrics.commit_count)
distinct_session_count: number
Number of distinct Claude Code sessions. On aggregated rows and in date-range mode: summed per-day distinct counts. A session essentially never spans a UTC day, so the sum is in practice the true distinct count.
[](#user_activity.data.items.claude_code_metrics.core_metrics.distinct_session_count)
lines_of_code: object { added_count, removed_count }
Lines of code added and removed via Claude Code.
added_count: number
Lines of code added
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code.added_count)
removed_count: number
Lines of code removed
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code.removed_count)
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code)
pull_request_count: number
Number of pull requests created via Claude Code
[](#user_activity.data.items.claude_code_metrics.core_metrics.pull_request_count)
[](#user_activity.data.items.claude_code_metrics.core_metrics)
tool_actions: object { edit_tool, multi_edit_tool, notebook_edit_tool, write_tool }
Per-tool accepted/rejected counts for Claude Code file modification tools.
edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool)
multi_edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool)
notebook_edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool)
write_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool)
[](#user_activity.data.items.claude_code_metrics.tool_actions)
[](#user_activity.data.items.claude_code_metrics)
cowork_metrics: object { action_count, connectors_used_count, dispatch_turn_count, 13 more }
Cowork activity metrics for a single user on a given day.
action_count: number
Number of tool actions completed in Cowork sessions
[](#user_activity.data.items.cowork_metrics.action_count)
connectors_used_count: number
Total number of connector invocations in Cowork sessions
[](#user_activity.data.items.cowork_metrics.connectors_used_count)
dispatch_turn_count: number
Number of Dispatch (background agent) turns completed
[](#user_activity.data.items.cowork_metrics.dispatch_turn_count)
distinct_connectors_used_count: number
Number of distinct connectors used in Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_connectors_used_count)
distinct_session_count: number
Number of distinct Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_session_count)
distinct_skills_used_count: number
Number of distinct skills used in Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_skills_used_count)
message_count: number
Number of messages sent in Cowork sessions
[](#user_activity.data.items.cowork_metrics.message_count)
skills_used_count: number
Total number of skill invocations in Cowork sessions
[](#user_activity.data.items.cowork_metrics.skills_used_count)
distinct_plugins_used_count: optional number
Number of distinct plugins used in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_plugins_used_count)
edit_tool_count: optional number
Number of successful Edit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.edit_tool_count)
file_edit_count: optional number
Number of successful file-edit tool calls (Edit, MultiEdit, Write, NotebookEdit) in Cowork sessions. Null, never 0, while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.file_edit_count)
multi_edit_tool_count: optional number
Number of successful MultiEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.multi_edit_tool_count)
notebook_edit_tool_count: optional number
Number of successful NotebookEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.notebook_edit_tool_count)
plugins_used_count: optional number
Total number of plugin invocations in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.plugins_used_count)
sessions_with_file_edits_count: optional number
Number of distinct Cowork sessions with at least one successful file-edit tool call. Null while the file-edit metrics are not enabled for this organization. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.sessions_with_file_edits_count)
write_tool_count: optional number
Number of successful Write tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.write_tool_count)
[](#user_activity.data.items.cowork_metrics)
design_metrics: object { distinct_projects_created_count, distinct_projects_used_count, distinct_session_count, message_count }
Claude Design activity metrics for a single user on a given day.
distinct_projects_created_count: number
Number of distinct Claude Design projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.design_metrics.distinct_projects_created_count)
distinct_projects_used_count: number
Number of distinct Claude Design projects the user worked in. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.design_metrics.distinct_projects_used_count)
distinct_session_count: number
Number of distinct Claude Design sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.design_metrics.distinct_session_count)
message_count: number
Number of messages sent in Claude Design sessions
[](#user_activity.data.items.design_metrics.message_count)
[](#user_activity.data.items.design_metrics)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single user on a given day, broken out by Office product.
excel: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.excel)
outlook: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.outlook)
powerpoint: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.powerpoint)
word: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.word)
[](#user_activity.data.items.office_metrics)
science_metrics: object { delegation_count, distinct_session_count, message_count, 2 more }
Claude Science activity metrics for a single user on a given day.
delegation_count: number
Number of delegations (handoffs to a specialized agent) in Claude Science sessions
[](#user_activity.data.items.science_metrics.delegation_count)
distinct_session_count: number
Number of distinct Claude Science sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.science_metrics.distinct_session_count)
message_count: number
Number of messages sent in Claude Science sessions
[](#user_activity.data.items.science_metrics.message_count)
remote_compute_job_count: number
Number of remote compute jobs launched from Claude Science sessions
[](#user_activity.data.items.science_metrics.remote_compute_job_count)
skills_used_count: number
Total number of skill invocations in Claude Science sessions
[](#user_activity.data.items.science_metrics.skills_used_count)
[](#user_activity.data.items.science_metrics)
web_search_count: number
Number of web searches performed
[](#user_activity.data.items.web_search_count)
distinct_user_count: optional number
Number of distinct active users represented by this row. Only set for grouped rollups (group_by\[\]); null for per-user rows. In date-range mode, recomputed as an exact distinct count of the group's active members over the requested window, never a sum of per-day values.
[](#user_activity.data.items.distinct_user_count)
last_activity_date: optional string
Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested date in single-day mode, and to the latest active day in \[starting_date, ending_date) in date-range rollup mode — never a day earlier than the window start. On filtered requests (filter\[\]) only days matching the filter count: with filter\[\]=rbac_group_id it is the last day the user was active while a member of that group, consistent with the row's other metrics. Null on grouped (group_by\[\]) rows. Omitted from the response while last-activity reporting is not enabled for this organization.
[](#user_activity.data.items.last_activity_date)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#user_activity.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#user_activity.data.items.rbac_group_name)
user: optional [AnalyticsUser](/docs/en/api/admin/analytics#analytics_user) { id, email_address }
User identifier.
id: string
Tagged user identifier (e.g. user\_...)
[](#user_activity.data.items.user%20%2B%20(resource)%20admin.analytics.id)
email_address: string
Email address of the user
[](#user_activity.data.items.user%20%2B%20(resource)%20admin.analytics.email_address)
[](#user_activity.data.items.user)
[](#user_activity.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#user_activity.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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. Available to organizations on a Claude Enterprise plan. Requires an API key with the `read:analytics` scope.
##### Query ParametersExpand Collapse
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.
[](#list.date)
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.
[](#list.ending_date)
filter: optional array of string
Filters as 'dimension
', e.g. filter\[\]=rbac_group_id:\<id\>. Repeat the param for OR within a dimension and across dimensions for AND. Unsupported dimensions return 400. 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 covered UTC day (time-of-usage attribution). At most 100 entries.
[](#list.filter)
group_by: optional array of string
Dimensions to break results out by, e.g. group_by\[\]=rbac_group_id. Supported dimensions vary by endpoint; an unsupported dimension returns 400. Grouped responses paginate like ungrouped ones via next_page. 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.
[](#list.group_by)
limit: optional number
Number of results per page (1-1000, default 100).
[](#list.limit)
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"
[](#list.order%5B0%5D)
"desc"
[](#list.order%5B1%5D)
[](#list.order)
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).
[](#list.order_by)
page: optional string
Opaque cursor from a previous response's next_page field.
[](#list.page)
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.
[](#list.starting_date)
##### ReturnsExpand Collapse
UserActivity object { data, next_page }
Response for GET /v1/organizations/analytics/users.
data: array of object { chat_metrics, claude_code_metrics, cowork_metrics, 9 more }
chat_metrics: object { connectors_used_count, distinct_artifacts_created_count, distinct_connectors_used_count, 9 more }
Claude.ai activity metrics for a single user on a given day.
connectors_used_count: number
Number of MCP connector invocations.
[](#user_activity.data.items.chat_metrics.connectors_used_count)
distinct_artifacts_created_count: number
Number of distinct artifacts created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.chat_metrics.distinct_artifacts_created_count)
distinct_connectors_used_count: number
Distinct claude.ai connectors this user used. Excludes calls whose connector could not be identified and all calls from organizations with zero data retention. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_connectors_used_count)
distinct_conversation_count: number
Number of distinct conversations the user participated in. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_conversation_count)
distinct_files_uploaded_count: number
Number of distinct files uploaded. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_files_uploaded_count)
distinct_projects_created_count: number
Number of distinct projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.chat_metrics.distinct_projects_created_count)
distinct_projects_used_count: number
Number of distinct projects used. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_projects_used_count)
distinct_shared_artifacts_viewed_count: number
Number of distinct shared artifacts the user viewed. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.chat_metrics.distinct_shared_artifacts_viewed_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.chat_metrics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.chat_metrics.message_count)
shared_conversations_viewed_count: number
Number of times the user opened a shared conversation in a project
[](#user_activity.data.items.chat_metrics.shared_conversations_viewed_count)
thinking_message_count: number
Number of messages that used extended thinking
[](#user_activity.data.items.chat_metrics.thinking_message_count)
[](#user_activity.data.items.chat_metrics)
claude_code_metrics: object { core_metrics, tool_actions }
Claude Code activity metrics for a single user on a given day.
core_metrics: object { commit_count, distinct_session_count, lines_of_code, pull_request_count }
Core Claude Code activity metrics for a single user on a given day.
commit_count: number
Number of commits made via Claude Code
[](#user_activity.data.items.claude_code_metrics.core_metrics.commit_count)
distinct_session_count: number
Number of distinct Claude Code sessions. On aggregated rows and in date-range mode: summed per-day distinct counts. A session essentially never spans a UTC day, so the sum is in practice the true distinct count.
[](#user_activity.data.items.claude_code_metrics.core_metrics.distinct_session_count)
lines_of_code: object { added_count, removed_count }
Lines of code added and removed via Claude Code.
added_count: number
Lines of code added
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code.added_count)
removed_count: number
Lines of code removed
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code.removed_count)
[](#user_activity.data.items.claude_code_metrics.core_metrics.lines_of_code)
pull_request_count: number
Number of pull requests created via Claude Code
[](#user_activity.data.items.claude_code_metrics.core_metrics.pull_request_count)
[](#user_activity.data.items.claude_code_metrics.core_metrics)
tool_actions: object { edit_tool, multi_edit_tool, notebook_edit_tool, write_tool }
Per-tool accepted/rejected counts for Claude Code file modification tools.
edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.edit_tool)
multi_edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.multi_edit_tool)
notebook_edit_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.notebook_edit_tool)
write_tool: [ToolActionCounts](/docs/en/api/admin/analytics#tool_action_counts) { accepted_count, rejected_count }
Accepted/rejected counts for a single Claude Code tool type.
accepted_count: number
Number of tool proposals accepted
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool%20%2B%20(resource)%20admin.analytics.accepted_count)
rejected_count: number
Number of tool proposals rejected
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool%20%2B%20(resource)%20admin.analytics.rejected_count)
[](#user_activity.data.items.claude_code_metrics.tool_actions.write_tool)
[](#user_activity.data.items.claude_code_metrics.tool_actions)
[](#user_activity.data.items.claude_code_metrics)
cowork_metrics: object { action_count, connectors_used_count, dispatch_turn_count, 13 more }
Cowork activity metrics for a single user on a given day.
action_count: number
Number of tool actions completed in Cowork sessions
[](#user_activity.data.items.cowork_metrics.action_count)
connectors_used_count: number
Total number of connector invocations in Cowork sessions
[](#user_activity.data.items.cowork_metrics.connectors_used_count)
dispatch_turn_count: number
Number of Dispatch (background agent) turns completed
[](#user_activity.data.items.cowork_metrics.dispatch_turn_count)
distinct_connectors_used_count: number
Number of distinct connectors used in Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_connectors_used_count)
distinct_session_count: number
Number of distinct Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_session_count)
distinct_skills_used_count: number
Number of distinct skills used in Cowork sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_skills_used_count)
message_count: number
Number of messages sent in Cowork sessions
[](#user_activity.data.items.cowork_metrics.message_count)
skills_used_count: number
Total number of skill invocations in Cowork sessions
[](#user_activity.data.items.cowork_metrics.skills_used_count)
distinct_plugins_used_count: optional number
Number of distinct plugins used in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.distinct_plugins_used_count)
edit_tool_count: optional number
Number of successful Edit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.edit_tool_count)
file_edit_count: optional number
Number of successful file-edit tool calls (Edit, MultiEdit, Write, NotebookEdit) in Cowork sessions. Null, never 0, while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.file_edit_count)
multi_edit_tool_count: optional number
Number of successful MultiEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.multi_edit_tool_count)
notebook_edit_tool_count: optional number
Number of successful NotebookEdit tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.notebook_edit_tool_count)
plugins_used_count: optional number
Total number of plugin invocations in Cowork sessions. Null while Cowork plugin-use metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.plugins_used_count)
sessions_with_file_edits_count: optional number
Number of distinct Cowork sessions with at least one successful file-edit tool call. Null while the file-edit metrics are not enabled for this organization. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.cowork_metrics.sessions_with_file_edits_count)
write_tool_count: optional number
Number of successful Write tool calls in Cowork sessions. Null while the file-edit metrics are not enabled for this organization.
[](#user_activity.data.items.cowork_metrics.write_tool_count)
[](#user_activity.data.items.cowork_metrics)
design_metrics: object { distinct_projects_created_count, distinct_projects_used_count, distinct_session_count, message_count }
Claude Design activity metrics for a single user on a given day.
distinct_projects_created_count: number
Number of distinct Claude Design projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
[](#user_activity.data.items.design_metrics.distinct_projects_created_count)
distinct_projects_used_count: number
Number of distinct Claude Design projects the user worked in. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.design_metrics.distinct_projects_used_count)
distinct_session_count: number
Number of distinct Claude Design sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.design_metrics.distinct_session_count)
message_count: number
Number of messages sent in Claude Design sessions
[](#user_activity.data.items.design_metrics.message_count)
[](#user_activity.data.items.design_metrics)
office_metrics: object { excel, outlook, powerpoint, word }
Office Agent activity metrics for a single user on a given day, broken out by Office product.
excel: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.excel%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.excel)
outlook: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.outlook%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.outlook)
powerpoint: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.powerpoint%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.powerpoint)
word: [OfficeProductMetrics](/docs/en/api/admin/analytics#office_product_metrics) { 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
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.connectors_used_count)
distinct_connectors_used_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_connectors_used_count)
distinct_session_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_session_count)
distinct_skills_used_count: number
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.
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.distinct_skills_used_count)
message_count: number
Number of messages sent
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.message_count)
skills_used_count: number
Number of skill invocations
[](#user_activity.data.items.office_metrics.word%20%2B%20(resource)%20admin.analytics.skills_used_count)
[](#user_activity.data.items.office_metrics.word)
[](#user_activity.data.items.office_metrics)
science_metrics: object { delegation_count, distinct_session_count, message_count, 2 more }
Claude Science activity metrics for a single user on a given day.
delegation_count: number
Number of delegations (handoffs to a specialized agent) in Claude Science sessions
[](#user_activity.data.items.science_metrics.delegation_count)
distinct_session_count: number
Number of distinct Claude Science sessions. Approximate (HLL, typical error \<2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
[](#user_activity.data.items.science_metrics.distinct_session_count)
message_count: number
Number of messages sent in Claude Science sessions
[](#user_activity.data.items.science_metrics.message_count)
remote_compute_job_count: number
Number of remote compute jobs launched from Claude Science sessions
[](#user_activity.data.items.science_metrics.remote_compute_job_count)
skills_used_count: number
Total number of skill invocations in Claude Science sessions
[](#user_activity.data.items.science_metrics.skills_used_count)
[](#user_activity.data.items.science_metrics)
web_search_count: number
Number of web searches performed
[](#user_activity.data.items.web_search_count)
distinct_user_count: optional number
Number of distinct active users represented by this row. Only set for grouped rollups (group_by\[\]); null for per-user rows. In date-range mode, recomputed as an exact distinct count of the group's active members over the requested window, never a sum of per-day values.
[](#user_activity.data.items.distinct_user_count)
last_activity_date: optional string
Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested date in single-day mode, and to the latest active day in \[starting_date, ending_date) in date-range rollup mode — never a day earlier than the window start. On filtered requests (filter\[\]) only days matching the filter count: with filter\[\]=rbac_group_id it is the last day the user was active while a member of that group, consistent with the row's other metrics. Null on grouped (group_by\[\]) rows. Omitted from the response while last-activity reporting is not enabled for this organization.
[](#user_activity.data.items.last_activity_date)
rbac_group_id: optional string
Tagged RBAC group identifier (rbac_group\_...), matching the spend-limits API spelling. Present only when the request grouped by rbac_group_id.
[](#user_activity.data.items.rbac_group_id)
rbac_group_name: optional string
Resolved RBAC group display name, alongside rbac_group_id when name resolution is available. Null if the group has been deleted or its name could not be resolved; rbac_group_id remains the stable key.
[](#user_activity.data.items.rbac_group_name)
user: optional [AnalyticsUser](/docs/en/api/admin/analytics#analytics_user) { id, email_address }
User identifier.
id: string
Tagged user identifier (e.g. user\_...)
[](#user_activity.data.items.user%20%2B%20(resource)%20admin.analytics.id)
email_address: string
Email address of the user
[](#user_activity.data.items.user%20%2B%20(resource)%20admin.analytics.email_address)
[](#user_activity.data.items.user)
[](#user_activity.data)
next_page: string
Opaque cursor for the next page, or null if no more results
[](#user_activity.next_page)
[](#user_activity)
List User Activity
```python
curl https://api.anthropic.com/v1/organizations/analytics/users \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": {
"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,
"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": "last_activity_date",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"user": {
"id": "id",
"email_address": "email_address"
}
}
],
"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": {
"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,
"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": "last_activity_date",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Api keys
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
# API Keys
##### [Retrieve API Key (Admin API)](/docs/en/api/admin/api_keys/retrieve)
GET/v1/organizations/api_keys/{api_key_id}
##### [List API Keys](/docs/en/api/admin/api_keys/list)
GET/v1/organizations/api_keys
##### [Update API Key](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
# List API Keys
GET/v1/organizations/api_keys
List API Keys
##### Query ParametersExpand Collapse
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.
[](#list.after_id)
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.
[](#list.before_id)
created_by_user_id: optional string
Filter by the ID of the User who created the object.
[](#list.created_by_user_id)
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
status: optional "active" or "archived" or "expired" or "inactive"
Filter by API key status.
One of the following:
"active"
[](#list.status%5B0%5D)
"archived"
[](#list.status%5B1%5D)
"expired"
[](#list.status%5B2%5D)
"inactive"
[](#list.status%5B3%5D)
[](#list.status)
workspace_id: optional string
Filter by Workspace ID.
[](#list.workspace_id)
##### ReturnsExpand Collapse
data: array of [APIKey](/docs/en/api/$shared#api_key) { id, created_at, created_by, 7 more }
id: string
ID of the API key.
[](#api_key.id)
created_at: string
RFC 3339 datetime string indicating when the API Key was created.
[](#api_key.created_at)
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.
[](#api_key.created_by.id)
type: string
Type of the actor that created the object.
[](#api_key.created_by.type)
[](#api_key.created_by)
expires_at: string
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
[](#api_key.expires_at)
name: string
Name of the API key.
[](#api_key.name)
partial_key_hint: string
Partially redacted hint for the API key.
[](#api_key.partial_key_hint)
principal: object { id, type }
The ID and type of the principal the API key acts as, or `null` if the key is not bound to a principal.
id: string
ID of the principal the API key acts as: a User ID (`user_...`) when the type is `user`, or a Service Account ID (`svac_...`) when the type is `service_account`.
[](#api_key.principal.id)
type: "service_account" or "user"
Type of the principal the API key acts as.
One of the following:
"service_account"
[](#api_key.principal.type%5B0%5D)
"user"
[](#api_key.principal.type%5B1%5D)
[](#api_key.principal.type)
[](#api_key.principal)
status: "active" or "archived" or "expired" or "inactive"
Status of the API key.
One of the following:
"active"
[](#api_key.status%5B0%5D)
"archived"
[](#api_key.status%5B1%5D)
"expired"
[](#api_key.status%5B2%5D)
"inactive"
[](#api_key.status%5B3%5D)
[](#api_key.status)
type: "api_key"
Object type.
For API Keys, this is always `"api_key"`.
[](#api_key.type)
workspace_id: string
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
[](#api_key.workspace_id)
[](#list)
first_id: string
First ID in the `data` list. Can be used as the `before_id` for the previous page.
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
last_id: string
Last ID in the `data` list. Can be used as the `after_id` for the next page.
[](#list)
List API Keys
```python
curl https://api.anthropic.com/v1/organizations/api_keys \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
# 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 ParametersExpand Collapse
api_key_id: string
ID of the API key.
[](#retrieve.api_key_id)
##### ReturnsExpand Collapse
APIKey object { id, created_at, created_by, 7 more }
id: string
ID of the API key.
[](#api_key.id)
created_at: string
RFC 3339 datetime string indicating when the API Key was created.
[](#api_key.created_at)
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.
[](#api_key.created_by.id)
type: string
Type of the actor that created the object.
[](#api_key.created_by.type)
[](#api_key.created_by)
expires_at: string
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
[](#api_key.expires_at)
name: string
Name of the API key.
[](#api_key.name)
partial_key_hint: string
Partially redacted hint for the API key.
[](#api_key.partial_key_hint)
principal: object { id, type }
The ID and type of the principal the API key acts as, or `null` if the key is not bound to a principal.
id: string
ID of the principal the API key acts as: a User ID (`user_...`) when the type is `user`, or a Service Account ID (`svac_...`) when the type is `service_account`.
[](#api_key.principal.id)
type: "service_account" or "user"
Type of the principal the API key acts as.
One of the following:
"service_account"
[](#api_key.principal.type%5B0%5D)
"user"
[](#api_key.principal.type%5B1%5D)
[](#api_key.principal.type)
[](#api_key.principal)
status: "active" or "archived" or "expired" or "inactive"
Status of the API key.
One of the following:
"active"
[](#api_key.status%5B0%5D)
"archived"
[](#api_key.status%5B1%5D)
"expired"
[](#api_key.status%5B2%5D)
"inactive"
[](#api_key.status%5B3%5D)
[](#api_key.status)
type: "api_key"
Object type.
For API Keys, this is always `"api_key"`.
[](#api_key.type)
workspace_id: string
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
[](#api_key.workspace_id)
[](#api_key)
Retrieve API Key (Admin API)
```python
curl https://api.anthropic.com/v1/organizations/api_keys/$API_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
Looking for your API keys? You can view and create them in [Settings → API keys](/settings/keys) in the Claude Console.
# Update API Key
POST/v1/organizations/api_keys/{api_key_id}
Update API Key
##### Path ParametersExpand Collapse
api_key_id: string
ID of the API key.
[](#update.api_key_id)
##### Body ParametersJSONExpand Collapse
name: optional string
Name of the API key.
[](#update.name)
status: optional "active" or "archived" or "inactive"
Status of the API key.
One of the following:
"active"
[](#update.status%5B0%5D)
"archived"
[](#update.status%5B1%5D)
"inactive"
[](#update.status%5B2%5D)
[](#update.status)
##### ReturnsExpand Collapse
APIKey object { id, created_at, created_by, 7 more }
id: string
ID of the API key.
[](#api_key.id)
created_at: string
RFC 3339 datetime string indicating when the API Key was created.
[](#api_key.created_at)
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.
[](#api_key.created_by.id)
type: string
Type of the actor that created the object.
[](#api_key.created_by.type)
[](#api_key.created_by)
expires_at: string
RFC 3339 datetime string indicating when the API Key expires, or `null` if it never expires.
[](#api_key.expires_at)
name: string
Name of the API key.
[](#api_key.name)
partial_key_hint: string
Partially redacted hint for the API key.
[](#api_key.partial_key_hint)
principal: object { id, type }
The ID and type of the principal the API key acts as, or `null` if the key is not bound to a principal.
id: string
ID of the principal the API key acts as: a User ID (`user_...`) when the type is `user`, or a Service Account ID (`svac_...`) when the type is `service_account`.
[](#api_key.principal.id)
type: "service_account" or "user"
Type of the principal the API key acts as.
One of the following:
"service_account"
[](#api_key.principal.type%5B0%5D)
"user"
[](#api_key.principal.type%5B1%5D)
[](#api_key.principal.type)
[](#api_key.principal)
status: "active" or "archived" or "expired" or "inactive"
Status of the API key.
One of the following:
"active"
[](#api_key.status%5B0%5D)
"archived"
[](#api_key.status%5B1%5D)
"expired"
[](#api_key.status%5B2%5D)
"inactive"
[](#api_key.status%5B3%5D)
[](#api_key.status)
type: "api_key"
Object type.
For API Keys, this is always `"api_key"`.
[](#api_key.type)
workspace_id: string
ID of the Workspace associated with the API key, or `null` if the API key belongs to the default Workspace.
[](#api_key.workspace_id)
[](#api_key)
Update API Key
```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_OAUTH_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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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": {
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"type": "user"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Cost report
# Cost Report
##### [Get Cost Report](/docs/en/api/admin/cost_report/retrieve)
GET/v1/organizations/cost_report
##### ModelsExpand Collapse
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.
[](#cost_report.data.items.ending_at)
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`.
[](#cost_report.data.items.results.items.amount)
context_window: "0-200k" or "200k-1M"
Input context window used. `null` if not grouping by description or for non-token costs.
One of the following:
"0-200k"
[](#cost_report.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#cost_report.data.items.results.items.context_window%5B1%5D)
[](#cost_report.data.items.results.items.context_window)
cost_type: "code_execution" or "session_usage" or "tokens" or "web_search"
Type of cost. `null` if not grouping by description.
One of the following:
"code_execution"
[](#cost_report.data.items.results.items.cost_type%5B0%5D)
"session_usage"
[](#cost_report.data.items.results.items.cost_type%5B1%5D)
"tokens"
[](#cost_report.data.items.results.items.cost_type%5B2%5D)
"web_search"
[](#cost_report.data.items.results.items.cost_type%5B3%5D)
[](#cost_report.data.items.results.items.cost_type)
currency: string
Currency code for the cost amount. Currently always `"USD"`.
[](#cost_report.data.items.results.items.currency)
description: string
Description of the cost item. `null` if not grouping by description.
[](#cost_report.data.items.results.items.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.
[](#cost_report.data.items.results.items.inference_geo)
model: string
Model name used. `null` if not grouping by description or for non-token costs.
[](#cost_report.data.items.results.items.model)
service_tier: "batch" or "standard"
Service tier used. `null` if not grouping by description or for non-token costs.
One of the following:
"batch"
[](#cost_report.data.items.results.items.service_tier%5B0%5D)
"standard"
[](#cost_report.data.items.results.items.service_tier%5B1%5D)
[](#cost_report.data.items.results.items.service_tier)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Type of token. `null` if not grouping by description or for non-token costs.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B2%5D)
"output_tokens"
[](#cost_report.data.items.results.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B4%5D)
[](#cost_report.data.items.results.items.token_type)
workspace_id: string
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
[](#cost_report.data.items.results.items.workspace_id)
[](#cost_report.data.items.results)
starting_at: string
Start of the time bucket (inclusive) in RFC 3339 format.
[](#cost_report.data.items.starting_at)
[](#cost_report.data)
has_more: boolean
Indicates if there are more results.
[](#cost_report.has_more)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#cost_report.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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Cost Report
GET/v1/organizations/cost_report
Get Cost Report
##### Query ParametersExpand Collapse
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.
[](#retrieve.starting_at)
bucket_width: optional "1d"
Time granularity of the response data.
[](#retrieve.bucket_width)
ending_at: optional string
Time buckets that end before this RFC 3339 timestamp will be returned.
[](#retrieve.ending_at)
group_by: optional array of "description" or "workspace_id"
Group by any subset of the available options.
One of the following:
"description"
[](#retrieve.group_by.items%5B0%5D)
"workspace_id"
[](#retrieve.group_by.items%5B1%5D)
[](#retrieve.group_by)
limit: optional number
Maximum number of time buckets to return in the response.
[](#retrieve.limit)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#retrieve.page)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
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.
[](#cost_report.data.items.ending_at)
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`.
[](#cost_report.data.items.results.items.amount)
context_window: "0-200k" or "200k-1M"
Input context window used. `null` if not grouping by description or for non-token costs.
One of the following:
"0-200k"
[](#cost_report.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#cost_report.data.items.results.items.context_window%5B1%5D)
[](#cost_report.data.items.results.items.context_window)
cost_type: "code_execution" or "session_usage" or "tokens" or "web_search"
Type of cost. `null` if not grouping by description.
One of the following:
"code_execution"
[](#cost_report.data.items.results.items.cost_type%5B0%5D)
"session_usage"
[](#cost_report.data.items.results.items.cost_type%5B1%5D)
"tokens"
[](#cost_report.data.items.results.items.cost_type%5B2%5D)
"web_search"
[](#cost_report.data.items.results.items.cost_type%5B3%5D)
[](#cost_report.data.items.results.items.cost_type)
currency: string
Currency code for the cost amount. Currently always `"USD"`.
[](#cost_report.data.items.results.items.currency)
description: string
Description of the cost item. `null` if not grouping by description.
[](#cost_report.data.items.results.items.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.
[](#cost_report.data.items.results.items.inference_geo)
model: string
Model name used. `null` if not grouping by description or for non-token costs.
[](#cost_report.data.items.results.items.model)
service_tier: "batch" or "standard"
Service tier used. `null` if not grouping by description or for non-token costs.
One of the following:
"batch"
[](#cost_report.data.items.results.items.service_tier%5B0%5D)
"standard"
[](#cost_report.data.items.results.items.service_tier%5B1%5D)
[](#cost_report.data.items.results.items.service_tier)
token_type: "cache_creation.ephemeral_1h_input_tokens" or "cache_creation.ephemeral_5m_input_tokens" or "cache_read_input_tokens" or 2 more
Type of token. `null` if not grouping by description or for non-token costs.
One of the following:
"cache_creation.ephemeral_1h_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B0%5D)
"cache_creation.ephemeral_5m_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B1%5D)
"cache_read_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B2%5D)
"output_tokens"
[](#cost_report.data.items.results.items.token_type%5B3%5D)
"uncached_input_tokens"
[](#cost_report.data.items.results.items.token_type%5B4%5D)
[](#cost_report.data.items.results.items.token_type)
workspace_id: string
ID of the Workspace this cost is associated with. `null` if not grouping by workspace or for the default workspace.
[](#cost_report.data.items.results.items.workspace_id)
[](#cost_report.data.items.results)
starting_at: string
Start of the time bucket (inclusive) in RFC 3339 format.
[](#cost_report.data.items.starting_at)
[](#cost_report.data)
has_more: boolean
Indicates if there are more results.
[](#cost_report.has_more)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#cost_report.next_page)
[](#cost_report)
Get Cost Report
```python
curl https://api.anthropic.com/v1/organizations/cost_report \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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 Sonnet 4 Usage - Input Tokens",
"inference_geo": "global",
"model": "claude-opus-4-6",
"service_tier": "standard",
"token_type": "uncached_input_tokens",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "2019-12-27T18:11:19.117Z"
}
```
##### 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 Sonnet 4 Usage - Input Tokens",
"inference_geo": "global",
"model": "claude-opus-4-6",
"service_tier": "standard",
"token_type": "uncached_input_tokens",
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
}
],
"starting_at": "2025-08-01T00:00:00Z"
}
],
"has_more": true,
"next_page": "2019-12-27T18:11:19.117Z"
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create External Key
POST/v1/organizations/external_keys
Create an external key config owned by the caller's organization.
##### Body ParametersJSONExpand Collapse
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.
[](#create.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#create.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#create.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#create.provider_config%5B0%5D.role_arn)
[](#create.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#create.provider_config%5B1%5D.key_name)
type: "gcp"
[](#create.provider_config%5B1%5D.type)
[](#create.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
Azure Key Vault provider configuration.
key_name: string
Name of the key within the vault.
[](#create.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#create.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#create.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#create.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#create.provider_config%5B2%5D.client_id)
[](#create.provider_config%5B2%5D)
[](#create.provider_config)
display_name: optional string
Human-friendly display name.
[](#create.display_name)
geo: optional "us"
Data residency geo. Only `us` is supported.
[](#create.geo)
##### ReturnsExpand Collapse
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.
[](#external_key_create_response.id)
created_at: string
[](#external_key_create_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_create_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_create_response.geo)
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.
[](#external_key_create_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_create_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_create_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_create_response.provider_config%5B0%5D.role_arn)
[](#external_key_create_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_create_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_create_response.provider_config%5B1%5D.type)
[](#external_key_create_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_create_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_create_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_create_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_create_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_create_response.provider_config%5B2%5D.client_id)
[](#external_key_create_response.provider_config%5B2%5D)
[](#external_key_create_response.provider_config)
type: "external_key"
[](#external_key_create_response.type)
updated_at: string
[](#external_key_create_response.updated_at)
Create External Key
```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_OAUTH_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",
"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",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# 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 ParametersExpand Collapse
external_key_id: string
ID of the External Key.
[](#delete.external_key_id)
##### ReturnsExpand Collapse
id: string
ID of the deleted External Key.
[](#external_key_delete_response.id)
type: "external_key_deleted"
[](#external_key_delete_response.type)
Delete External Key
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
External keys
# External Keys
##### [Create External Key](/docs/en/api/admin/external_keys/create)
POST/v1/organizations/external_keys
##### [List External Keys](/docs/en/api/admin/external_keys/list)
GET/v1/organizations/external_keys
##### [Get External Key](/docs/en/api/admin/external_keys/retrieve)
GET/v1/organizations/external_keys/{external_key_id}
##### [Update External Key](/docs/en/api/admin/external_keys/update)
POST/v1/organizations/external_keys/{external_key_id}
##### [Delete External Key](/docs/en/api/admin/external_keys/delete)
DELETE/v1/organizations/external_keys/{external_key_id}
##### [Validate External Key](/docs/en/api/admin/external_keys/validate)
POST/v1/organizations/external_keys/{external_key_id}/validate
##### ModelsExpand Collapse
ExternalKeyCreateResponse object { id, created_at, display_name, 4 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).
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.
[](#external_key_create_response.id)
created_at: string
[](#external_key_create_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_create_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_create_response.geo)
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.
[](#external_key_create_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_create_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_create_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_create_response.provider_config%5B0%5D.role_arn)
[](#external_key_create_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_create_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_create_response.provider_config%5B1%5D.type)
[](#external_key_create_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_create_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_create_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_create_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_create_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_create_response.provider_config%5B2%5D.client_id)
[](#external_key_create_response.provider_config%5B2%5D)
[](#external_key_create_response.provider_config)
type: "external_key"
[](#external_key_create_response.type)
updated_at: string
[](#external_key_create_response.updated_at)
[](#external_key_create_response)
ExternalKeyListResponse object { id, created_at, display_name, 4 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).
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.
[](#external_key_list_response.id)
created_at: string
[](#external_key_list_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_list_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_list_response.geo)
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.
[](#external_key_list_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_list_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_list_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_list_response.provider_config%5B0%5D.role_arn)
[](#external_key_list_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_list_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_list_response.provider_config%5B1%5D.type)
[](#external_key_list_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_list_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_list_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_list_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_list_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_list_response.provider_config%5B2%5D.client_id)
[](#external_key_list_response.provider_config%5B2%5D)
[](#external_key_list_response.provider_config)
type: "external_key"
[](#external_key_list_response.type)
updated_at: string
[](#external_key_list_response.updated_at)
[](#external_key_list_response)
ExternalKeyRetrieveResponse object { id, created_at, display_name, 4 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).
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.
[](#external_key_retrieve_response.id)
created_at: string
[](#external_key_retrieve_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_retrieve_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_retrieve_response.geo)
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.
[](#external_key_retrieve_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_retrieve_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_retrieve_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_retrieve_response.provider_config%5B0%5D.role_arn)
[](#external_key_retrieve_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_retrieve_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_retrieve_response.provider_config%5B1%5D.type)
[](#external_key_retrieve_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_retrieve_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_retrieve_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_retrieve_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_retrieve_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_retrieve_response.provider_config%5B2%5D.client_id)
[](#external_key_retrieve_response.provider_config%5B2%5D)
[](#external_key_retrieve_response.provider_config)
type: "external_key"
[](#external_key_retrieve_response.type)
updated_at: string
[](#external_key_retrieve_response.updated_at)
[](#external_key_retrieve_response)
ExternalKeyUpdateResponse object { id, created_at, display_name, 4 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).
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.
[](#external_key_update_response.id)
created_at: string
[](#external_key_update_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_update_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_update_response.geo)
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.
[](#external_key_update_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_update_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_update_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_update_response.provider_config%5B0%5D.role_arn)
[](#external_key_update_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_update_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_update_response.provider_config%5B1%5D.type)
[](#external_key_update_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_update_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_update_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_update_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_update_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_update_response.provider_config%5B2%5D.client_id)
[](#external_key_update_response.provider_config%5B2%5D)
[](#external_key_update_response.provider_config)
type: "external_key"
[](#external_key_update_response.type)
updated_at: string
[](#external_key_update_response.updated_at)
[](#external_key_update_response)
ExternalKeyDeleteResponse object { id, type }
id: string
ID of the deleted External Key.
[](#external_key_delete_response.id)
type: "external_key_deleted"
[](#external_key_delete_response.type)
[](#external_key_delete_response)
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
Error message when status is `failure`. Null otherwise.
[](#external_key_validate_response.error)
status: "failure" or "success"
`success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`.
One of the following:
"failure"
[](#external_key_validate_response.status%5B0%5D)
"success"
[](#external_key_validate_response.status%5B1%5D)
[](#external_key_validate_response.status)
type: "external_key_validation"
[](#external_key_validate_response.type)
[](#external_key_validate_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### ReturnsExpand Collapse
data: array of object { id, created_at, display_name, 4 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.
[](#external_key_list_response.id)
created_at: string
[](#external_key_list_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_list_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_list_response.geo)
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.
[](#external_key_list_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_list_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_list_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_list_response.provider_config%5B0%5D.role_arn)
[](#external_key_list_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_list_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_list_response.provider_config%5B1%5D.type)
[](#external_key_list_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_list_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_list_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_list_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_list_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_list_response.provider_config%5B2%5D.client_id)
[](#external_key_list_response.provider_config%5B2%5D)
[](#external_key_list_response.provider_config)
type: "external_key"
[](#external_key_list_response.type)
updated_at: string
[](#external_key_list_response.updated_at)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results. Pass as `?page=` to fetch the next page.
[](#list)
List External Keys
```python
curl https://api.anthropic.com/v1/organizations/external_keys \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"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",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# 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 ParametersExpand Collapse
external_key_id: string
ID of the External Key.
[](#retrieve.external_key_id)
##### ReturnsExpand Collapse
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.
[](#external_key_retrieve_response.id)
created_at: string
[](#external_key_retrieve_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_retrieve_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_retrieve_response.geo)
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.
[](#external_key_retrieve_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_retrieve_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_retrieve_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_retrieve_response.provider_config%5B0%5D.role_arn)
[](#external_key_retrieve_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_retrieve_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_retrieve_response.provider_config%5B1%5D.type)
[](#external_key_retrieve_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_retrieve_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_retrieve_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_retrieve_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_retrieve_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_retrieve_response.provider_config%5B2%5D.client_id)
[](#external_key_retrieve_response.provider_config%5B2%5D)
[](#external_key_retrieve_response.provider_config)
type: "external_key"
[](#external_key_retrieve_response.type)
updated_at: string
[](#external_key_retrieve_response.updated_at)
Get External Key
```python
curl https://api.anthropic.com/v1/organizations/external_keys/$EXTERNAL_KEY_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"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",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# 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 ParametersExpand Collapse
external_key_id: string
ID of the External Key.
[](#update.external_key_id)
##### Body ParametersJSONExpand Collapse
display_name: optional string
Human-friendly display name.
[](#update.display_name)
geo: optional "us"
Data residency geo. Only `us` is supported.
[](#update.geo)
provider_config: optional 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.
[](#update.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#update.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#update.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#update.provider_config%5B0%5D.role_arn)
[](#update.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#update.provider_config%5B1%5D.key_name)
type: "gcp"
[](#update.provider_config%5B1%5D.type)
[](#update.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
Azure Key Vault provider configuration.
key_name: string
Name of the key within the vault.
[](#update.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#update.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#update.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#update.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#update.provider_config%5B2%5D.client_id)
[](#update.provider_config%5B2%5D)
[](#update.provider_config)
##### ReturnsExpand Collapse
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.
[](#external_key_update_response.id)
created_at: string
[](#external_key_update_response.created_at)
display_name: string
Human-friendly display name. Null if none was set.
[](#external_key_update_response.display_name)
geo: string
Data residency geo. Selects which regional validator handles this key's encrypt/decrypt roundtrips.
[](#external_key_update_response.geo)
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.
[](#external_key_update_response.provider_config%5B0%5D.kms_arn)
type: "aws"
[](#external_key_update_response.provider_config%5B0%5D.type)
region: optional string
AWS region. Derived from kms_arn if omitted.
[](#external_key_update_response.provider_config%5B0%5D.region)
role_arn: optional stringDeprecated
IAM role ARN. Deprecated — Anthropic reaches the KMS key via a managed intermediate role; this field is ignored.
[](#external_key_update_response.provider_config%5B0%5D.role_arn)
[](#external_key_update_response.provider_config%5B0%5D)
Gcp object { key_name, type }
key_name: string
Full resource name of the Cloud KMS key.
[](#external_key_update_response.provider_config%5B1%5D.key_name)
type: "gcp"
[](#external_key_update_response.provider_config%5B1%5D.type)
[](#external_key_update_response.provider_config%5B1%5D)
Azure object { key_name, tenant_id, type, 2 more }
key_name: string
Name of the key within the vault.
[](#external_key_update_response.provider_config%5B2%5D.key_name)
tenant_id: string
Azure AD tenant ID.
[](#external_key_update_response.provider_config%5B2%5D.tenant_id)
type: "azure"
[](#external_key_update_response.provider_config%5B2%5D.type)
vault_uri: string
Key Vault data-plane URI — https://\<vault-name\>.vault.azure.net or https://\<hsm-name\>.managedhsm.azure.net.
[](#external_key_update_response.provider_config%5B2%5D.vault_uri)
client_id: optional string
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.
[](#external_key_update_response.provider_config%5B2%5D.client_id)
[](#external_key_update_response.provider_config%5B2%5D)
[](#external_key_update_response.provider_config)
type: "external_key"
[](#external_key_update_response.type)
updated_at: string
[](#external_key_update_response.updated_at)
Update External Key
```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_OAUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "ekey_01SDCCSbTxrXDpWc1phhtcfK",
"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",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Validate
# 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 ParametersExpand Collapse
external_key_id: string
ID of the External Key.
[](#validate.external_key_id)
##### ReturnsExpand Collapse
error: string
Error message when status is `failure`. Null otherwise.
[](#external_key_validate_response.error)
status: "failure" or "success"
`success` — encrypt/decrypt roundtrip succeeded. `failure` — the roundtrip failed or timed out; see `error`.
One of the following:
"failure"
[](#external_key_validate_response.status%5B0%5D)
"success"
[](#external_key_validate_response.status%5B1%5D)
[](#external_key_validate_response.status)
type: "external_key_validation"
[](#external_key_validate_response.type)
Validate External Key
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Federation issuers
# Federation Issuers
##### [Create Federation Issuer](/docs/en/api/admin/federation_issuers/create)
POST/v1/organizations/federation_issuers
##### [Get Federation Issuer](/docs/en/api/admin/federation_issuers/retrieve)
GET/v1/organizations/federation_issuers/{federation_issuer_id}
##### [List Federation Issuers](/docs/en/api/admin/federation_issuers/list)
GET/v1/organizations/federation_issuers
##### [Update Federation Issuer](/docs/en/api/admin/federation_issuers/update)
POST/v1/organizations/federation_issuers/{federation_issuer_id}
##### [Archive Federation Issuer](/docs/en/api/admin/federation_issuers/archive)
POST/v1/organizations/federation_issuers/{federation_issuer_id}/archive
##### ModelsExpand Collapse
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.
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# Archive Federation Issuer
POST/v1/organizations/federation_issuers/{federation_issuer_id}/archive
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.
Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_issuer_id: string
ID of the federation issuer to archive.
[](#archive.federation_issuer_id)
##### Header ParametersExpand Collapse
"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.
[](#archive.anthropic-beta)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
[](#federation_issuer)
Archive Federation Issuer
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Federation Issuer
POST/v1/organizations/federation_issuers
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.
Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
issuer_url: string
The `iss` claim value to match against.
[](#create.issuer_url)
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
[](#create.name)
check_jti: optional boolean
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.
[](#create.check_jti)
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"
[](#create.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#create.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#create.jwks%5B0%5D.discovery_base)
[](#create.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#create.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#create.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#create.jwks%5B1%5D.ca_cert_pem)
[](#create.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#create.jwks%5B2%5D.keys)
type: "inline"
[](#create.jwks%5B2%5D.type)
[](#create.jwks%5B2%5D)
[](#create.jwks)
max_jwt_lifetime_seconds: optional number
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.
[](#create.max_jwt_lifetime_seconds)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
[](#federation_issuer)
Create Federation Issuer
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Federation Issuers
GET/v1/organizations/federation_issuers
List federation issuers in your organization.
Archived issuers are excluded unless `include_archived=true`.
##### Query ParametersExpand Collapse
include_archived: optional boolean
Include archived resources. Defaults to false.
[](#list.include_archived)
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [FederationIssuer](/docs/en/api/admin/federation_issuers#federation_issuer) { id, archived_at, archived_by_actor_id, 12 more }
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results.
[](#list)
List Federation Issuers
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Federation Issuer
GET/v1/organizations/federation_issuers/{federation_issuer_id}
Retrieve a federation issuer by its ID (`fdis_...`).
##### Path ParametersExpand Collapse
federation_issuer_id: string
ID of the federation issuer.
[](#retrieve.federation_issuer_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
[](#federation_issuer)
Get Federation Issuer
```python
curl https://api.anthropic.com/v1/organizations/federation_issuers/$FEDERATION_ISSUER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Federation Issuer
POST/v1/organizations/federation_issuers/{federation_issuer_id}
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_issuer_id: string
ID of the federation issuer to update.
[](#update.federation_issuer_id)
##### Header ParametersExpand Collapse
"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.
[](#update.anthropic-beta)
##### Body ParametersJSONExpand Collapse
check_jti: optional 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.
[](#update.check_jti)
issuer_url: optional string
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.
[](#update.issuer_url)
jwks: optional object { type, ca_cert_pem, discovery_base } or object { type, url, ca_cert_pem } or object { keys, type }
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"
[](#update.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#update.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#update.jwks%5B0%5D.discovery_base)
[](#update.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#update.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#update.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#update.jwks%5B1%5D.ca_cert_pem)
[](#update.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#update.jwks%5B2%5D.keys)
type: "inline"
[](#update.jwks%5B2%5D.type)
[](#update.jwks%5B2%5D)
[](#update.jwks)
jwks_polling_disabled: optional boolean
Only `false` is accepted, to re-enable polling after the system pauses it. Polling is paused automatically; sending `true` is rejected.
[](#update.jwks_polling_disabled)
max_jwt_lifetime_seconds: optional 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.
[](#update.max_jwt_lifetime_seconds)
name: optional string
Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
[](#update.name)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation issuer.
[](#federation_issuer.id)
archived_at: string
If set, all rules referencing this issuer reject token exchange.
[](#federation_issuer.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this issuer.
[](#federation_issuer.archived_by_actor_id)
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.
[](#federation_issuer.check_jti)
created_at: string
When this issuer was created.
[](#federation_issuer.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this issuer.
[](#federation_issuer.created_by_actor_id)
issuer_url: string
The `iss` claim value. Incoming JWTs must match exactly.
[](#federation_issuer.issuer_url)
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"
[](#federation_issuer.jwks%5B0%5D.type)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B0%5D.ca_cert_pem)
discovery_base: optional string
Set when the discovery URL differs from `issuer_url`.
[](#federation_issuer.jwks%5B0%5D.discovery_base)
[](#federation_issuer.jwks%5B0%5D)
ExplicitURL object { type, url, ca_cert_pem }
JWKS fetched from a fixed endpoint.
type: "explicit_url"
[](#federation_issuer.jwks%5B1%5D.type)
url: string
JWKS endpoint.
[](#federation_issuer.jwks%5B1%5D.url)
ca_cert_pem: optional string
Optional custom CA (PEM) for TLS verification of the JWKS fetch.
[](#federation_issuer.jwks%5B1%5D.ca_cert_pem)
[](#federation_issuer.jwks%5B1%5D)
Inline object { keys, type }
JWKS supplied directly; no network fetch.
keys: array of map\[unknown\]
Inline JWK objects.
[](#federation_issuer.jwks%5B2%5D.keys)
type: "inline"
[](#federation_issuer.jwks%5B2%5D.type)
[](#federation_issuer.jwks%5B2%5D)
[](#federation_issuer.jwks)
jwks_polling_disabled_at: string
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.
[](#federation_issuer.jwks_polling_disabled_at)
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.
[](#federation_issuer.max_jwt_lifetime_seconds)
name: string
Admin-chosen slug identifier.
[](#federation_issuer.name)
poll_status: object { consecutive_failures, last_fetched_at, next_poll_at }
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.
[](#federation_issuer.poll_status.consecutive_failures)
last_fetched_at: string
When the last successful fetch completed.
[](#federation_issuer.poll_status.last_fetched_at)
next_poll_at: string
When the next fetch is scheduled. Null if paused.
[](#federation_issuer.poll_status.next_poll_at)
[](#federation_issuer.poll_status)
type: "federation_issuer"
[](#federation_issuer.type)
updated_at: string
When this issuer was last updated.
[](#federation_issuer.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this issuer.
[](#federation_issuer.updated_by_actor_id)
[](#federation_issuer)
Update Federation Issuer
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# Archive Federation Rule
POST/v1/organizations/federation_rules/{federation_rule_id}/archive
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. Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule to archive.
[](#archive.federation_rule_id)
##### Header ParametersExpand Collapse
"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.
[](#archive.anthropic-beta)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#federation_rule)
Archive Federation Rule
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Federation Rule
POST/v1/organizations/federation_rules
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. Admin API keys are not accepted.
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
issuer_id: string
Tagged ID of the federation issuer.
[](#create.issuer_id)
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
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.
[](#create.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#create.match.claims)
condition: optional string
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.
[](#create.match.condition)
subject_prefix: optional string
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`.
[](#create.match.subject_prefix)
[](#create.match)
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
[](#create.name)
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.
[](#create.oauth_scope)
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.
[](#create.target.service_account_id)
type: "service_account"
[](#create.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#create.target.service_account_name)
[](#create.target)
applies_to_all_workspaces: optional boolean
When true, enable this rule for every workspace in the org (including workspaces created later).
[](#create.applies_to_all_workspaces)
attributes: optional map\[string\]
CEL expressions `{name: expr}` extracting named values from claims. Not yet supported; any non-empty value is rejected with 400.
[](#create.attributes)
description: optional string
Optional free-text description.
[](#create.description)
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.
[](#create.token_lifetime_seconds)
workspace_id: optional string
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.
[](#create.workspace_id)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#federation_rule)
Create Federation Rule
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Federation rules
# Federation Rules
##### [Create Federation Rule](/docs/en/api/admin/federation_rules/create)
POST/v1/organizations/federation_rules
##### [Get Federation Rule](/docs/en/api/admin/federation_rules/retrieve)
GET/v1/organizations/federation_rules/{federation_rule_id}
##### [List Federation Rules](/docs/en/api/admin/federation_rules/list)
GET/v1/organizations/federation_rules
##### [Update Federation Rule](/docs/en/api/admin/federation_rules/update)
POST/v1/organizations/federation_rules/{federation_rule_id}
##### [Archive Federation Rule](/docs/en/api/admin/federation_rules/archive)
POST/v1/organizations/federation_rules/{federation_rule_id}/archive
##### ModelsExpand Collapse
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.
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#federation_rule)
#### Federation RulesWorkspaces
##### [List Federation Rule Workspaces](/docs/en/api/admin/federation_rules/workspaces/list)
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Add Federation Rule Workspace](/docs/en/api/admin/federation_rules/workspaces/create)
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Remove Federation Rule Workspace](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Federation Rules
GET/v1/organizations/federation_rules
List federation rules in your organization.
Optionally filter by issuer with `issuer_id`. Archived rules are excluded unless `include_archived=true`.
##### Query ParametersExpand Collapse
include_archived: optional boolean
Include archived resources. Defaults to false.
[](#list.include_archived)
issuer_id: optional string
Filter to rules referencing this federation issuer.
[](#list.issuer_id)
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [FederationRule](/docs/en/api/admin/federation_rules#federation_rule) { id, applies_to_all_workspaces, archived_at, 17 more }
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results.
[](#list)
List Federation Rules
```python
curl https://api.anthropic.com/v1/organizations/federation_rules \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Federation Rule
GET/v1/organizations/federation_rules/{federation_rule_id}
Retrieve a federation rule by its ID (`fdrl_...`).
##### Path ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule.
[](#retrieve.federation_rule_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#federation_rule)
Get Federation Rule
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Federation Rule
POST/v1/organizations/federation_rules/{federation_rule_id}
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. Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule to update.
[](#update.federation_rule_id)
##### Header ParametersExpand Collapse
"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.
[](#update.anthropic-beta)
##### Body ParametersJSONExpand Collapse
applies_to_all_workspaces: optional boolean
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.
[](#update.applies_to_all_workspaces)
attributes: optional map\[string\]
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.
[](#update.attributes)
description: optional string
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string).
[](#update.description)
match: optional object { audience, claims, condition, subject_prefix }
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
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.
[](#update.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#update.match.claims)
condition: optional string
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.
[](#update.match.condition)
subject_prefix: optional string
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`.
[](#update.match.subject_prefix)
[](#update.match)
name: optional string
Replaces the slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
[](#update.name)
oauth_scope: optional string
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.
[](#update.oauth_scope)
target: optional object { service_account_id, type, service_account_name }
Bind to a fixed service account by ID.
service_account_id: string
Tagged ID of the service account to mint tokens for.
[](#update.target.service_account_id)
type: "service_account"
[](#update.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#update.target.service_account_name)
[](#update.target)
token_lifetime_seconds: optional number
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.
[](#update.token_lifetime_seconds)
workspace_id: optional string
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.
[](#update.workspace_id)
##### ReturnsExpand Collapse
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.
id: string
Tagged ID of the federation rule.
[](#federation_rule.id)
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.
[](#federation_rule.applies_to_all_workspaces)
archived_at: string
If set, this rule is archived and rejects token exchange.
[](#federation_rule.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this rule.
[](#federation_rule.archived_by_actor_id)
attributes: map\[string\]
CEL expressions extracting named values from claims. Not yet supported; always null.
[](#federation_rule.attributes)
created_at: string
When this rule was created.
[](#federation_rule.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this rule.
[](#federation_rule.created_by_actor_id)
description: string
Optional free-text description.
[](#federation_rule.description)
issuer_id: string
Tagged ID of the issuer whose tokens this rule accepts.
[](#federation_rule.issuer_id)
issuer_name: string
Issuer's display name at read time.
[](#federation_rule.issuer_name)
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
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.
[](#federation_rule.match.audience)
claims: optional map\[string\]
Exact-match `{claim: value}` pairs against top-level claims. Only string-valued claims can be matched; use `condition` for non-string claims.
[](#federation_rule.match.claims)
condition: optional string
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.
[](#federation_rule.match.condition)
subject_prefix: optional string
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`.
[](#federation_rule.match.subject_prefix)
[](#federation_rule.match)
name: string
Admin-chosen slug identifier.
[](#federation_rule.name)
oauth_scope: string
Space-separated OAuth scopes granted on the minted token.
[](#federation_rule.oauth_scope)
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.
[](#federation_rule.target.service_account_id)
type: "service_account"
[](#federation_rule.target.type)
service_account_name: optional string
Service account's display name at read time. Ignored on writes.
[](#federation_rule.target.service_account_name)
[](#federation_rule.target)
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.
[](#federation_rule.token_lifetime_seconds)
type: "federation_rule"
[](#federation_rule.type)
updated_at: string
When this rule was last updated.
[](#federation_rule.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this rule.
[](#federation_rule.updated_by_actor_id)
workspace_id: string
Legacy single-workspace binding. Prefer `workspace_ids` and the `/federation_rules/{federation_rule_id}/workspaces` sub-resource for managing workspace enablement.
[](#federation_rule.workspace_id)
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).
[](#federation_rule.workspace_ids)
[](#federation_rule)
Update Federation Rule
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Workspaces
# Workspaces
##### [List Federation Rule Workspaces](/docs/en/api/admin/federation_rules/workspaces/list)
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Add Federation Rule Workspace](/docs/en/api/admin/federation_rules/workspaces/create)
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
##### [Remove Federation Rule Workspace](/docs/en/api/admin/federation_rules/workspaces/delete)
DELETE/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}
##### ModelsExpand Collapse
WorkspaceListResponse object { created_at, created_by_actor_id, federation_rule_id, 3 more }
created_at: string
When this workspace was enabled for the rule.
[](#workspace_list_response.created_at)
created_by_actor_id: string
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
[](#workspace_list_response.created_by_actor_id)
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_list_response.federation_rule_id)
type: "federation_rule_workspace"
[](#workspace_list_response.type)
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
[](#workspace_list_response.workspace_id)
workspace_name: string
Workspace display name. Populated when listing; null in the enable response.
[](#workspace_list_response.workspace_name)
[](#workspace_list_response)
WorkspaceCreateResponse object { created_at, created_by_actor_id, federation_rule_id, 3 more }
created_at: string
When this workspace was enabled for the rule.
[](#workspace_create_response.created_at)
created_by_actor_id: string
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
[](#workspace_create_response.created_by_actor_id)
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_create_response.federation_rule_id)
type: "federation_rule_workspace"
[](#workspace_create_response.type)
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
[](#workspace_create_response.workspace_id)
workspace_name: string
Workspace display name. Populated when listing; null in the enable response.
[](#workspace_create_response.workspace_name)
[](#workspace_create_response)
WorkspaceDeleteResponse object { federation_rule_id, type, workspace_id }
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_delete_response.federation_rule_id)
type: "federation_rule_workspace_deleted"
[](#workspace_delete_response.type)
workspace_id: string
Tagged ID of the workspace named in the delete request. Removal is idempotent.
[](#workspace_delete_response.workspace_id)
[](#workspace_delete_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Add Federation Rule Workspace
POST/v1/organizations/federation_rules/{federation_rule_id}/workspaces
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. Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule.
[](#create.federation_rule_id)
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
workspace_id: string
Tagged ID of the workspace to enable this rule for.
[](#create.workspace_id)
##### ReturnsExpand Collapse
created_at: string
When this workspace was enabled for the rule.
[](#workspace_create_response.created_at)
created_by_actor_id: string
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
[](#workspace_create_response.created_by_actor_id)
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_create_response.federation_rule_id)
type: "federation_rule_workspace"
[](#workspace_create_response.type)
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
[](#workspace_create_response.workspace_id)
workspace_name: string
Workspace display name. Populated when listing; null in the enable response.
[](#workspace_create_response.workspace_name)
Add Federation Rule Workspace
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Remove Federation Rule Workspace
DELETE/v1/organizations/federation_rules/{federation_rule_id}/workspaces/{workspace_id}
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. Admin API keys are not accepted.
##### Path ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule.
[](#delete.federation_rule_id)
workspace_id: string
ID of the workspace to disable for.
[](#delete.workspace_id)
##### Header ParametersExpand Collapse
"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.
[](#delete.anthropic-beta)
##### ReturnsExpand Collapse
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_delete_response.federation_rule_id)
type: "federation_rule_workspace_deleted"
[](#workspace_delete_response.type)
workspace_id: string
Tagged ID of the workspace named in the delete request. Removal is idempotent.
[](#workspace_delete_response.workspace_id)
Remove Federation Rule Workspace
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Federation Rule Workspaces
GET/v1/organizations/federation_rules/{federation_rule_id}/workspaces
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 ParametersExpand Collapse
federation_rule_id: string
ID of the federation rule.
[](#list.federation_rule_id)
##### Query ParametersExpand Collapse
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
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.
[](#workspace_list_response.created_at)
created_by_actor_id: string
Tagged ID (`user_...` or `svac_...`) of the actor that enabled this workspace for the rule, if known.
[](#workspace_list_response.created_by_actor_id)
federation_rule_id: string
Tagged ID of the federation rule.
[](#workspace_list_response.federation_rule_id)
type: "federation_rule_workspace"
[](#workspace_list_response.type)
workspace_id: string
Tagged ID of the workspace this rule is enabled for.
[](#workspace_list_response.workspace_id)
workspace_name: string
Workspace display name. Populated when listing; null in the enable response.
[](#workspace_list_response.workspace_name)
[](#list)
next_page: string
Opaque cursor for the next page; null when there are no more results.
[](#list)
List Federation Rule Workspaces
```python
curl https://api.anthropic.com/v1/organizations/federation_rules/$FEDERATION_RULE_ID/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Invite
POST/v1/organizations/invites
For Claude Enterprise organizations, this endpoint's availability is in beta.
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 ParametersJSONExpand Collapse
email: string
Email of the User.
[](#create.email)
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 (beta) accept `user` and `managed`.
One of the following:
"billing"
[](#create.role%5B0%5D)
"claude_code_user"
[](#create.role%5B1%5D)
"developer"
[](#create.role%5B2%5D)
"managed"
[](#create.role%5B3%5D)
"user"
[](#create.role%5B4%5D)
[](#create.role)
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 (beta), and requires the key to carry the `write:rbac_groups` scope.
[](#create.rbac_group_ids)
##### ReturnsExpand Collapse
Invite object { id, accepted_at, email, 6 more }
id: string
ID of the Invite.
[](#invite.id)
accepted_at: string
RFC 3339 datetime string indicating when the Invite was accepted, or null.
[](#invite.accepted_at)
email: string
Email of the User being invited.
[](#invite.email)
expires_at: string
RFC 3339 datetime string indicating when the Invite expires.
[](#invite.expires_at)
invited_at: string
RFC 3339 datetime string indicating when the Invite was created.
[](#invite.invited_at)
rbac_group_ids: array of string
RBAC group IDs recorded on the Invite (beta, Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none.
[](#invite.rbac_group_ids)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#invite.role%5B0%5D)
"billing"
[](#invite.role%5B1%5D)
"claude_code_user"
[](#invite.role%5B2%5D)
"developer"
[](#invite.role%5B3%5D)
"managed"
[](#invite.role%5B4%5D)
"membership_admin"
[](#invite.role%5B5%5D)
"owner"
[](#invite.role%5B6%5D)
"primary_owner"
[](#invite.role%5B7%5D)
"user"
[](#invite.role%5B8%5D)
[](#invite.role)
status: "accepted" or "deleted" or "expired" or "pending"
Status of the Invite.
One of the following:
"accepted"
[](#invite.status%5B0%5D)
"deleted"
[](#invite.status%5B1%5D)
"expired"
[](#invite.status%5B2%5D)
"pending"
[](#invite.status%5B3%5D)
[](#invite.status)
type: "invite"
Object type.
For Invites, this is always `"invite"`.
[](#invite.type)
[](#invite)
Create Invite
```python
curl https://api.anthropic.com/v1/organizations/invites \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-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": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Delete Invite
DELETE/v1/organizations/invites/{invite_id}
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Path ParametersExpand Collapse
invite_id: string
ID of the Invite.
[](#delete.invite_id)
##### ReturnsExpand Collapse
id: string
ID of the Invite.
[](#invite_delete_response.id)
type: "invite_deleted"
Deleted object type.
For Invites, this is always `"invite_deleted"`.
[](#invite_delete_response.type)
Delete Invite
```python
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Invites
# Invites
##### [Create Invite](/docs/en/api/admin/invites/create)
POST/v1/organizations/invites
##### [Get Invite](/docs/en/api/admin/invites/retrieve)
GET/v1/organizations/invites/{invite_id}
##### [List Invites](/docs/en/api/admin/invites/list)
GET/v1/organizations/invites
##### [Delete Invite](/docs/en/api/admin/invites/delete)
DELETE/v1/organizations/invites/{invite_id}
##### ModelsExpand Collapse
Invite object { id, accepted_at, email, 6 more }
id: string
ID of the Invite.
[](#invite.id)
accepted_at: string
RFC 3339 datetime string indicating when the Invite was accepted, or null.
[](#invite.accepted_at)
email: string
Email of the User being invited.
[](#invite.email)
expires_at: string
RFC 3339 datetime string indicating when the Invite expires.
[](#invite.expires_at)
invited_at: string
RFC 3339 datetime string indicating when the Invite was created.
[](#invite.invited_at)
rbac_group_ids: array of string
RBAC group IDs recorded on the Invite (beta, Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none.
[](#invite.rbac_group_ids)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#invite.role%5B0%5D)
"billing"
[](#invite.role%5B1%5D)
"claude_code_user"
[](#invite.role%5B2%5D)
"developer"
[](#invite.role%5B3%5D)
"managed"
[](#invite.role%5B4%5D)
"membership_admin"
[](#invite.role%5B5%5D)
"owner"
[](#invite.role%5B6%5D)
"primary_owner"
[](#invite.role%5B7%5D)
"user"
[](#invite.role%5B8%5D)
[](#invite.role)
status: "accepted" or "deleted" or "expired" or "pending"
Status of the Invite.
One of the following:
"accepted"
[](#invite.status%5B0%5D)
"deleted"
[](#invite.status%5B1%5D)
"expired"
[](#invite.status%5B2%5D)
"pending"
[](#invite.status%5B3%5D)
[](#invite.status)
type: "invite"
Object type.
For Invites, this is always `"invite"`.
[](#invite.type)
[](#invite)
InviteDeleteResponse object { id, type }
id: string
ID of the Invite.
[](#invite_delete_response.id)
type: "invite_deleted"
Deleted object type.
For Invites, this is always `"invite_deleted"`.
[](#invite_delete_response.type)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Invites
GET/v1/organizations/invites
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Query ParametersExpand Collapse
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.
[](#list.after_id)
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.
[](#list.before_id)
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
##### ReturnsExpand Collapse
data: array of [Invite](/docs/en/api/admin/invites#invite) { id, accepted_at, email, 6 more }
id: string
ID of the Invite.
[](#invite.id)
accepted_at: string
RFC 3339 datetime string indicating when the Invite was accepted, or null.
[](#invite.accepted_at)
email: string
Email of the User being invited.
[](#invite.email)
expires_at: string
RFC 3339 datetime string indicating when the Invite expires.
[](#invite.expires_at)
invited_at: string
RFC 3339 datetime string indicating when the Invite was created.
[](#invite.invited_at)
rbac_group_ids: array of string
RBAC group IDs recorded on the Invite (beta, Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none.
[](#invite.rbac_group_ids)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#invite.role%5B0%5D)
"billing"
[](#invite.role%5B1%5D)
"claude_code_user"
[](#invite.role%5B2%5D)
"developer"
[](#invite.role%5B3%5D)
"managed"
[](#invite.role%5B4%5D)
"membership_admin"
[](#invite.role%5B5%5D)
"owner"
[](#invite.role%5B6%5D)
"primary_owner"
[](#invite.role%5B7%5D)
"user"
[](#invite.role%5B8%5D)
[](#invite.role)
status: "accepted" or "deleted" or "expired" or "pending"
Status of the Invite.
One of the following:
"accepted"
[](#invite.status%5B0%5D)
"deleted"
[](#invite.status%5B1%5D)
"expired"
[](#invite.status%5B2%5D)
"pending"
[](#invite.status%5B3%5D)
[](#invite.status)
type: "invite"
Object type.
For Invites, this is always `"invite"`.
[](#invite.type)
[](#list)
first_id: string
First ID in the `data` list. Can be used as the `before_id` for the previous page.
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
last_id: string
Last ID in the `data` list. Can be used as the `after_id` for the next page.
[](#list)
List Invites
```python
curl https://api.anthropic.com/v1/organizations/invites \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Invite
GET/v1/organizations/invites/{invite_id}
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Path ParametersExpand Collapse
invite_id: string
ID of the Invite.
[](#retrieve.invite_id)
##### ReturnsExpand Collapse
Invite object { id, accepted_at, email, 6 more }
id: string
ID of the Invite.
[](#invite.id)
accepted_at: string
RFC 3339 datetime string indicating when the Invite was accepted, or null.
[](#invite.accepted_at)
email: string
Email of the User being invited.
[](#invite.email)
expires_at: string
RFC 3339 datetime string indicating when the Invite expires.
[](#invite.expires_at)
invited_at: string
RFC 3339 datetime string indicating when the Invite was created.
[](#invite.invited_at)
rbac_group_ids: array of string
RBAC group IDs recorded on the Invite (beta, Claude Enterprise organizations), to be assigned to the User when the Invite is accepted. `[]` when none.
[](#invite.rbac_group_ids)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#invite.role%5B0%5D)
"billing"
[](#invite.role%5B1%5D)
"claude_code_user"
[](#invite.role%5B2%5D)
"developer"
[](#invite.role%5B3%5D)
"managed"
[](#invite.role%5B4%5D)
"membership_admin"
[](#invite.role%5B5%5D)
"owner"
[](#invite.role%5B6%5D)
"primary_owner"
[](#invite.role%5B7%5D)
"user"
[](#invite.role%5B8%5D)
[](#invite.role)
status: "accepted" or "deleted" or "expired" or "pending"
Status of the Invite.
One of the following:
"accepted"
[](#invite.status%5B0%5D)
"deleted"
[](#invite.status%5B1%5D)
"expired"
[](#invite.status%5B2%5D)
"pending"
[](#invite.status%5B3%5D)
[](#invite.status)
type: "invite"
Object type.
For Invites, this is always `"invite"`.
[](#invite.type)
[](#invite)
Get Invite
```python
curl https://api.anthropic.com/v1/organizations/invites/$INVITE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#archive.tunnel_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#archive.anthropic-beta)
##### ReturnsExpand Collapse
id: string
ID of the Tunnel.
[](#mcp_tunnel_archive_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_archive_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_archive_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_archive_response.display_name)
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.
[](#mcp_tunnel_archive_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_archive_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_archive_response.workspace_id)
Archive Tunnel
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Mcp tunnels
# MCP Tunnels
##### [Get Tunnel](/docs/en/api/admin/mcp_tunnels/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}
##### [List Tunnels](/docs/en/api/admin/mcp_tunnels/list)
Deprecated
GET/v1/organizations/tunnels
##### [Reveal Tunnel Token](/docs/en/api/admin/mcp_tunnels/reveal_token)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/reveal_token
##### [Rotate Tunnel Token](/docs/en/api/admin/mcp_tunnels/rotate_token)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/rotate_token
##### [Archive Tunnel](/docs/en/api/admin/mcp_tunnels/archive)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/archive
##### ModelsExpand Collapse
MCPTunnelRetrieveResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
[](#mcp_tunnel_retrieve_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_retrieve_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_retrieve_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_retrieve_response.display_name)
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.
[](#mcp_tunnel_retrieve_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_retrieve_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_retrieve_response.workspace_id)
[](#mcp_tunnel_retrieve_response)
MCPTunnelListResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
[](#mcp_tunnel_list_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_list_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_list_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_list_response.display_name)
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.
[](#mcp_tunnel_list_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_list_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_list_response.workspace_id)
[](#mcp_tunnel_list_response)
MCPTunnelRevealTokenResponse object { id, tunnel_token, type }
id: string
Stable identifier for the current token value. Changes when the token is rotated.
[](#mcp_tunnel_reveal_token_response.id)
tunnel_token: string
The tunnel's connection token.
[](#mcp_tunnel_reveal_token_response.tunnel_token)
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
[](#mcp_tunnel_reveal_token_response.type)
[](#mcp_tunnel_reveal_token_response)
MCPTunnelRotateTokenResponse object { id, tunnel_token, type }
id: string
Stable identifier for the current token value. Changes when the token is rotated.
[](#mcp_tunnel_rotate_token_response.id)
tunnel_token: string
The tunnel's connection token.
[](#mcp_tunnel_rotate_token_response.tunnel_token)
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
[](#mcp_tunnel_rotate_token_response.type)
[](#mcp_tunnel_rotate_token_response)
MCPTunnelArchiveResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
[](#mcp_tunnel_archive_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_archive_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_archive_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_archive_response.display_name)
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.
[](#mcp_tunnel_archive_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_archive_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_archive_response.workspace_id)
[](#mcp_tunnel_archive_response)
#### MCP TunnelsTunnel Certificates
##### [Create Tunnel Certificate](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/create)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Get Tunnel Certificate](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
##### [List Tunnel Certificates](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/list)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Archive Tunnel Certificate](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
include_archived: optional boolean
Include archived tunnels in the results. Archived tunnels are excluded by default.
[](#list.include_archived)
limit: optional number
Maximum number of tunnels to return in a single page.
[](#list.limit)
page: optional string
Opaque pagination cursor from a previous response's `next_page`. Omit to fetch the first page.
[](#list.page)
workspace_id: optional string
Return only tunnels in this Workspace. Accepts a `wrkspc_`-prefixed Workspace ID; omit to list tunnels across all Workspaces.
[](#list.workspace_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel.
[](#mcp_tunnel_list_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_list_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_list_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_list_response.display_name)
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.
[](#mcp_tunnel_list_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_list_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_list_response.workspace_id)
[](#list)
next_page: string
Opaque cursor for the next page, or `null` if there are no more results.
[](#list)
List Tunnels
```python
curl https://api.anthropic.com/v1/organizations/tunnels \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#retrieve.tunnel_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
id: string
ID of the Tunnel.
[](#mcp_tunnel_retrieve_response.id)
archived_at: string
RFC 3339 datetime string indicating when the Tunnel was archived, or `null` if it is not archived.
[](#mcp_tunnel_retrieve_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the Tunnel was created.
[](#mcp_tunnel_retrieve_response.created_at)
display_name: string
Human-readable name for the Tunnel (1–255 characters), or `null` if unset.
[](#mcp_tunnel_retrieve_response.display_name)
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.
[](#mcp_tunnel_retrieve_response.domain)
type: "tunnel"
Object type. Always `tunnel` for Tunnels.
[](#mcp_tunnel_retrieve_response.type)
workspace_id: string
ID of the Workspace this Tunnel belongs to, or `null` for the default Workspace. Immutable after creation.
[](#mcp_tunnel_retrieve_response.workspace_id)
Get Tunnel
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Reveal token
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#reveal_token.tunnel_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#reveal_token.anthropic-beta)
##### ReturnsExpand Collapse
id: string
Stable identifier for the current token value. Changes when the token is rotated.
[](#mcp_tunnel_reveal_token_response.id)
tunnel_token: string
The tunnel's connection token.
[](#mcp_tunnel_reveal_token_response.tunnel_token)
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
[](#mcp_tunnel_reveal_token_response.type)
Reveal Tunnel Token
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Rotate token
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#rotate_token.tunnel_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#rotate_token.anthropic-beta)
##### Body ParametersJSONExpand Collapse
reason: optional string
Optional free-text reason for the rotation, recorded for audit.
[](#rotate_token.reason)
##### ReturnsExpand Collapse
id: string
Stable identifier for the current token value. Changes when the token is rotated.
[](#mcp_tunnel_rotate_token_response.id)
tunnel_token: string
The tunnel's connection token.
[](#mcp_tunnel_rotate_token_response.tunnel_token)
type: "tunnel_token"
Object type. Always `tunnel_token` for Tunnel Tokens.
[](#mcp_tunnel_rotate_token_response.type)
Rotate Tunnel Token
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Tunnel certificates
# Tunnel Certificates
##### [Create Tunnel Certificate](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/create)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Get Tunnel Certificate](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/retrieve)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}
##### [List Tunnel Certificates](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/list)
Deprecated
GET/v1/organizations/tunnels/{tunnel_id}/certificates
##### [Archive Tunnel Certificate](/docs/en/api/admin/mcp_tunnels/tunnel_certificates/archive)
Deprecated
POST/v1/organizations/tunnels/{tunnel_id}/certificates/{certificate_id}/archive
##### ModelsExpand Collapse
TunnelCertificateCreateResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_create_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_create_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_create_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_create_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_create_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_create_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_create_response.type)
[](#tunnel_certificate_create_response)
TunnelCertificateRetrieveResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_retrieve_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_retrieve_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_retrieve_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_retrieve_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_retrieve_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_retrieve_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_retrieve_response.type)
[](#tunnel_certificate_retrieve_response)
TunnelCertificateListResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_list_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_list_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_list_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_list_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_list_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_list_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_list_response.type)
[](#tunnel_certificate_list_response)
TunnelCertificateArchiveResponse object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_archive_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_archive_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_archive_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_archive_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_archive_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_archive_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_archive_response.type)
[](#tunnel_certificate_archive_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#archive.tunnel_id)
certificate_id: string
ID of the Tunnel Certificate.
[](#archive.certificate_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#archive.anthropic-beta)
##### ReturnsExpand Collapse
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_archive_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_archive_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_archive_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_archive_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_archive_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_archive_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_archive_response.type)
Archive Tunnel Certificate
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#create.tunnel_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
ca_certificate_pem: string
PEM-encoded X.509 CA certificate. Must contain exactly one certificate and no private-key material.
[](#create.ca_certificate_pem)
##### ReturnsExpand Collapse
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_create_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_create_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_create_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_create_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_create_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_create_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_create_response.type)
Create Tunnel Certificate
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#list.tunnel_id)
##### Query ParametersExpand Collapse
include_archived: optional boolean
Include archived certificates in the results. Archived certificates are excluded by default.
[](#list.include_archived)
limit: optional number
Maximum number of certificates to return.
[](#list.limit)
page: optional string
A tunnel has at most two active certificates, so this list is not paginated.
[](#list.page)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of object { id, archived_at, created_at, 4 more }
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_list_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_list_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_list_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_list_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_list_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_list_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_list_response.type)
[](#list)
next_page: string
Opaque cursor for the next page, or `null` if there are no more results.
[](#list)
List Tunnel Certificates
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# 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 ParametersExpand Collapse
tunnel_id: string
ID of the Tunnel.
[](#retrieve.tunnel_id)
certificate_id: string
ID of the Tunnel Certificate.
[](#retrieve.certificate_id)
##### Header ParametersExpand Collapse
"anthropic-beta": array of "mcp-tunnels-2026-05-19"
Required for all Tunnel endpoints.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
id: string
ID of the Tunnel Certificate.
[](#tunnel_certificate_retrieve_response.id)
archived_at: string
RFC 3339 datetime string indicating when the certificate was archived, or `null` if it is not archived.
[](#tunnel_certificate_retrieve_response.archived_at)
created_at: string
RFC 3339 datetime string indicating when the certificate was registered.
[](#tunnel_certificate_retrieve_response.created_at)
expires_at: string
RFC 3339 datetime string indicating when the certificate expires, or `null` if it does not expire.
[](#tunnel_certificate_retrieve_response.expires_at)
fingerprint: string
The certificate's SHA-256 fingerprint, as a lowercase hex string.
[](#tunnel_certificate_retrieve_response.fingerprint)
tunnel_id: string
ID of the Tunnel this certificate is registered against.
[](#tunnel_certificate_retrieve_response.tunnel_id)
type: "tunnel_certificate"
Object type. Always `tunnel_certificate` for Tunnel Certificates.
[](#tunnel_certificate_retrieve_response.type)
Get Tunnel Certificate
```python
curl https://api.anthropic.com/v1/organizations/tunnels/$TUNNEL_ID/certificates/$CERTIFICATE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Organizations
# Organizations
##### [Get Current Organization](/docs/en/api/admin/organizations/me)
GET/v1/organizations/me
##### ModelsExpand Collapse
Organization object { id, name, type }
id: string
ID of the Organization.
[](#organization.id)
name: string
Name of the Organization.
[](#organization.name)
type: "organization"
Object type.
For Organizations, this is always `"organization"`.
[](#organization.type)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Me
# Get Current Organization
GET/v1/organizations/me
Retrieve information about the organization associated with the authenticated API key.
##### ReturnsExpand Collapse
Organization object { id, name, type }
id: string
ID of the Organization.
[](#organization.id)
name: string
Name of the Organization.
[](#organization.name)
type: "organization"
Object type.
For Organizations, this is always `"organization"`.
[](#organization.type)
[](#organization)
Get Current Organization
```python
curl https://api.anthropic.com/v1/organizations/me \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Rate limits
# Rate Limits
##### [List Organization Rate Limits](/docs/en/api/admin/rate_limits/list)
GET/v1/organizations/rate_limits
##### ModelsExpand Collapse
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: "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"
[](#rate_limit_list_response.data.items.group_type%5B0%5D)
"files"
[](#rate_limit_list_response.data.items.group_type%5B1%5D)
"model_group"
[](#rate_limit_list_response.data.items.group_type%5B2%5D)
"skills"
[](#rate_limit_list_response.data.items.group_type%5B3%5D)
"token_count"
[](#rate_limit_list_response.data.items.group_type%5B4%5D)
"web_search"
[](#rate_limit_list_response.data.items.group_type%5B5%5D)
[](#rate_limit_list_response.data.items.group_type)
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`).
[](#rate_limit_list_response.data.items.limits.items.type)
value: number
The configured limit value for this limiter type.
[](#rate_limit_list_response.data.items.limits.items.value)
[](#rate_limit_list_response.data.items.limits)
models: array of string
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
[](#rate_limit_list_response.data.items.models)
type: "rate_limit"
Object type. Always `rate_limit` for organization rate-limit entries.
[](#rate_limit_list_response.data.items.type)
[](#rate_limit_list_response.data)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#rate_limit_list_response.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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.
##### Query ParametersExpand Collapse
group_type: optional "batch" or "files" or "model_group" or 3 more
Filter by group type.
One of the following:
"batch"
[](#list.group_type%5B0%5D)
"files"
[](#list.group_type%5B1%5D)
"model_group"
[](#list.group_type%5B2%5D)
"skills"
[](#list.group_type%5B3%5D)
"token_count"
[](#list.group_type%5B4%5D)
"web_search"
[](#list.group_type%5B5%5D)
[](#list.group_type)
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.
[](#list.model)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### ReturnsExpand Collapse
data: array of object { group_type, limits, models, type }
Rate-limit entries for the organization, one per group.
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"
[](#rate_limit_list_response.data.items.group_type%5B0%5D)
"files"
[](#rate_limit_list_response.data.items.group_type%5B1%5D)
"model_group"
[](#rate_limit_list_response.data.items.group_type%5B2%5D)
"skills"
[](#rate_limit_list_response.data.items.group_type%5B3%5D)
"token_count"
[](#rate_limit_list_response.data.items.group_type%5B4%5D)
"web_search"
[](#rate_limit_list_response.data.items.group_type%5B5%5D)
[](#rate_limit_list_response.data.items.group_type)
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`).
[](#rate_limit_list_response.data.items.limits.items.type)
value: number
The configured limit value for this limiter type.
[](#rate_limit_list_response.data.items.limits.items.value)
[](#rate_limit_list_response.data.items.limits)
models: array of string
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
[](#rate_limit_list_response.data.items.models)
type: "rate_limit"
Object type. Always `rate_limit` for organization rate-limit entries.
[](#rate_limit_list_response.data.items.type)
[](#rate_limit_list_response.data)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#rate_limit_list_response.next_page)
List Organization Rate Limits
```python
curl https://api.anthropic.com/v1/organizations/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Rbac groups
# RBAC Groups
##### [List RBAC Groups](/docs/en/api/admin/rbac_groups/list)
GET/v1/organizations/rbac_groups
##### [Get RBAC Group](/docs/en/api/admin/rbac_groups/retrieve)
GET/v1/organizations/rbac_groups/{group_id}
##### [Create RBAC Group](/docs/en/api/admin/rbac_groups/create)
POST/v1/organizations/rbac_groups
##### [Update RBAC Group](/docs/en/api/admin/rbac_groups/update)
POST/v1/organizations/rbac_groups/{group_id}
##### [Delete RBAC Group](/docs/en/api/admin/rbac_groups/delete)
DELETE/v1/organizations/rbac_groups/{group_id}
##### ModelsExpand Collapse
RbacGroup object { id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
[](#rbac_group.id)
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
[](#rbac_group.created_at)
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#rbac_group.name)
roles: array of string
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.
[](#rbac_group.roles)
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"
[](#rbac_group.source_type%5B0%5D)
"scim"
[](#rbac_group.source_type%5B1%5D)
[](#rbac_group.source_type)
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
[](#rbac_group.type)
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
[](#rbac_group.updated_at)
[](#rbac_group)
RbacGroupDeleted object { id, type }
id: string
ID of the RBAC Group.
[](#rbac_group_deleted.id)
type: "rbac_group_deleted"
Deleted object type.
For RBAC Groups, this is always `"rbac_group_deleted"`.
[](#rbac_group_deleted.type)
[](#rbac_group_deleted)
#### RBAC GroupsMembers
##### [List RBAC Group Members](/docs/en/api/admin/rbac_groups/members/list)
GET/v1/organizations/rbac_groups/{group_id}/members
##### [Add RBAC Group Member](/docs/en/api/admin/rbac_groups/members/create)
POST/v1/organizations/rbac_groups/{group_id}/members
##### [Remove RBAC Group Member](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# 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 in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#create.name)
##### ReturnsExpand Collapse
RbacGroup object { id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
[](#rbac_group.id)
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
[](#rbac_group.created_at)
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#rbac_group.name)
roles: array of string
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.
[](#rbac_group.roles)
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"
[](#rbac_group.source_type%5B0%5D)
"scim"
[](#rbac_group.source_type%5B1%5D)
[](#rbac_group.source_type)
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
[](#rbac_group.type)
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
[](#rbac_group.updated_at)
[](#rbac_group)
Create RBAC Group
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# 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.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#delete.group_id)
##### Header ParametersExpand Collapse
"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.
[](#delete.anthropic-beta)
##### ReturnsExpand Collapse
RbacGroupDeleted object { id, type }
id: string
ID of the RBAC Group.
[](#rbac_group_deleted.id)
type: "rbac_group_deleted"
Deleted object type.
For RBAC Groups, this is always `"rbac_group_deleted"`.
[](#rbac_group_deleted.type)
[](#rbac_group_deleted)
Delete RBAC Group
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List RBAC Groups
GET/v1/organizations/rbac_groups
List RBAC Groups in the Claude Enterprise tenant.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Query ParametersExpand Collapse
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [RbacGroup](/docs/en/api/admin/rbac_groups#rbac_group) { id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
[](#rbac_group.id)
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
[](#rbac_group.created_at)
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#rbac_group.name)
roles: array of string
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.
[](#rbac_group.roles)
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"
[](#rbac_group.source_type%5B0%5D)
"scim"
[](#rbac_group.source_type%5B1%5D)
[](#rbac_group.source_type)
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
[](#rbac_group.type)
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
[](#rbac_group.updated_at)
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#list)
List RBAC Groups
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Members
# Members
##### [List RBAC Group Members](/docs/en/api/admin/rbac_groups/members/list)
GET/v1/organizations/rbac_groups/{group_id}/members
##### [Add RBAC Group Member](/docs/en/api/admin/rbac_groups/members/create)
POST/v1/organizations/rbac_groups/{group_id}/members
##### [Remove RBAC Group Member](/docs/en/api/admin/rbac_groups/members/delete)
DELETE/v1/organizations/rbac_groups/{group_id}/members/{user_id}
##### ModelsExpand Collapse
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.
[](#rbac_group_member.created_at)
email: string
Email of the User.
[](#rbac_group_member.email)
group_id: string
ID of the RBAC Group.
[](#rbac_group_member.group_id)
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
[](#rbac_group_member.type)
user_id: string
ID of the User.
[](#rbac_group_member.user_id)
[](#rbac_group_member)
RbacGroupMemberDeleted object { group_id, type, user_id }
group_id: string
ID of the RBAC Group.
[](#rbac_group_member_deleted.group_id)
type: "rbac_group_member_deleted"
Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`.
[](#rbac_group_member_deleted.type)
user_id: string
ID of the User.
[](#rbac_group_member_deleted.user_id)
[](#rbac_group_member_deleted)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# 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.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#create.group_id)
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
user_id: string
ID of the User.
[](#create.user_id)
##### ReturnsExpand Collapse
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.
[](#rbac_group_member.created_at)
email: string
Email of the User.
[](#rbac_group_member.email)
group_id: string
ID of the RBAC Group.
[](#rbac_group_member.group_id)
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
[](#rbac_group_member.type)
user_id: string
ID of the User.
[](#rbac_group_member.user_id)
[](#rbac_group_member)
Add RBAC Group Member
```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 "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# 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.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#delete.group_id)
user_id: string
ID of the User.
[](#delete.user_id)
##### Header ParametersExpand Collapse
"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.
[](#delete.anthropic-beta)
##### ReturnsExpand Collapse
RbacGroupMemberDeleted object { group_id, type, user_id }
group_id: string
ID of the RBAC Group.
[](#rbac_group_member_deleted.group_id)
type: "rbac_group_member_deleted"
Deleted object type. For RBAC Group Members, this is always `"rbac_group_member_deleted"`.
[](#rbac_group_member_deleted.type)
user_id: string
ID of the User.
[](#rbac_group_member_deleted.user_id)
[](#rbac_group_member_deleted)
Remove RBAC Group Member
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List RBAC Group Members
GET/v1/organizations/rbac_groups/{group_id}/members
List members of an RBAC Group.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#list.group_id)
##### Query ParametersExpand Collapse
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [RbacGroupMember](/docs/en/api/admin/rbac_groups/members#rbac_group_member) { created_at, email, group_id, 2 more }
created_at: string
RFC 3339 timestamp of when the User was added to the RBAC Group.
[](#rbac_group_member.created_at)
email: string
Email of the User.
[](#rbac_group_member.email)
group_id: string
ID of the RBAC Group.
[](#rbac_group_member.group_id)
type: "rbac_group_member"
Object type.
For RBAC Group Members, this is always `"rbac_group_member"`.
[](#rbac_group_member.type)
user_id: string
ID of the User.
[](#rbac_group_member.user_id)
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#list)
List RBAC Group Members
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get RBAC Group
GET/v1/organizations/rbac_groups/{group_id}
Retrieve an RBAC Group by ID.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#retrieve.group_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
RbacGroup object { id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
[](#rbac_group.id)
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
[](#rbac_group.created_at)
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#rbac_group.name)
roles: array of string
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.
[](#rbac_group.roles)
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"
[](#rbac_group.source_type%5B0%5D)
"scim"
[](#rbac_group.source_type%5B1%5D)
[](#rbac_group.source_type)
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
[](#rbac_group.type)
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
[](#rbac_group.updated_at)
[](#rbac_group)
Get RBAC Group
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# 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.
The RBAC Groups API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
group_id: string
ID of the RBAC Group.
[](#update.group_id)
##### Header ParametersExpand Collapse
"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.
[](#update.anthropic-beta)
##### Body ParametersJSONExpand Collapse
name: optional string
Name of the RBAC Group. Not uniqueness-enforced.
[](#update.name)
##### ReturnsExpand Collapse
RbacGroup object { id, created_at, name, 4 more }
id: string
ID of the RBAC Group.
[](#rbac_group.id)
created_at: string
RFC 3339 timestamp of when the RBAC Group was created.
[](#rbac_group.created_at)
name: string
Name of the RBAC Group. Not uniqueness-enforced.
[](#rbac_group.name)
roles: array of string
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.
[](#rbac_group.roles)
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"
[](#rbac_group.source_type%5B0%5D)
"scim"
[](#rbac_group.source_type%5B1%5D)
[](#rbac_group.source_type)
type: "rbac_group"
Object type.
For RBAC Groups, this is always `"rbac_group"`.
[](#rbac_group.type)
updated_at: string
RFC 3339 timestamp of when the RBAC Group was last updated.
[](#rbac_group.updated_at)
[](#rbac_group)
Update RBAC Group
```python
curl https://api.anthropic.com/v1/organizations/rbac_groups/$GROUP_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Rbac roles
# RBAC Roles
##### [List RBAC Roles](/docs/en/api/admin/rbac_roles/list)
GET/v1/organizations/rbac_roles
##### [Get RBAC Role](/docs/en/api/admin/rbac_roles/retrieve)
GET/v1/organizations/rbac_roles/{role_id}
##### ModelsExpand Collapse
RbacRole object { id, created_at, name, 2 more }
id: string
ID of the RBAC Role.
[](#rbac_role.id)
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
[](#rbac_role.created_at)
name: string
Name of the RBAC Role.
[](#rbac_role.name)
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
[](#rbac_role.type)
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
[](#rbac_role.updated_at)
[](#rbac_role)
#### RBAC RolesPermissions
##### [List RBAC Role Permissions](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List RBAC Roles
GET/v1/organizations/rbac_roles
List RBAC Roles in the organization.
The RBAC Roles API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Query ParametersExpand Collapse
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [RbacRole](/docs/en/api/admin/rbac_roles#rbac_role) { id, created_at, name, 2 more }
id: string
ID of the RBAC Role.
[](#rbac_role.id)
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
[](#rbac_role.created_at)
name: string
Name of the RBAC Role.
[](#rbac_role.name)
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
[](#rbac_role.type)
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
[](#rbac_role.updated_at)
[](#list)
has_more: boolean
Indicates whether there are more results beyond this page.
[](#list)
next_page: string
Opaque cursor for the next page. Pass as the `page` parameter on the next request.
[](#list)
List RBAC Roles
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Permissions
# Permissions
##### [List RBAC Role Permissions](/docs/en/api/admin/rbac_roles/permissions/list)
GET/v1/organizations/rbac_roles/{role_id}/permissions
##### ModelsExpand Collapse
RbacRolePermission object { action, resource, type }
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`).
[](#rbac_role_permission.action)
resource: object { organization_id, type } or object { connector_id, tool_name, type } or object { connector_id, scope, type } 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 { organization_id, type }
organization_id: string
UUID of the organization the permission applies to.
[](#rbac_role_permission.resource%5B0%5D.organization_id)
type: "organization"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B0%5D.type)
[](#rbac_role_permission.resource%5B0%5D)
ConnectorTool object { connector_id, tool_name, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B1%5D.connector_id)
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.
[](#rbac_role_permission.resource%5B1%5D.tool_name)
type: "connector_tool"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B1%5D.type)
[](#rbac_role_permission.resource%5B1%5D)
ConnectorScope object { connector_id, scope, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B2%5D.connector_id)
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.
[](#rbac_role_permission.resource%5B2%5D.scope)
type: "connector_scope"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B2%5D.type)
[](#rbac_role_permission.resource%5B2%5D)
Connector object { connector_id, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B3%5D.connector_id)
type: "connector"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B3%5D.type)
[](#rbac_role_permission.resource%5B3%5D)
AllConnectors object { type }
type: "all_connectors"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B4%5D.type)
[](#rbac_role_permission.resource%5B4%5D)
[](#rbac_role_permission.resource)
type: "rbac_role_permission"
Object type.
For RBAC Role Permissions, this is always `"rbac_role_permission"`.
[](#rbac_role_permission.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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List RBAC Role Permissions
GET/v1/organizations/rbac_roles/{role_id}/permissions
List the permissions an RBAC Role grants.
The RBAC Roles API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
role_id: string
ID of the RBAC Role.
[](#list.role_id)
##### Query ParametersExpand Collapse
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [RbacRolePermission](/docs/en/api/admin/rbac_roles/permissions#rbac_role_permission) { action, resource, type }
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`).
[](#rbac_role_permission.action)
resource: object { organization_id, type } or object { connector_id, tool_name, type } or object { connector_id, scope, type } 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 { organization_id, type }
organization_id: string
UUID of the organization the permission applies to.
[](#rbac_role_permission.resource%5B0%5D.organization_id)
type: "organization"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B0%5D.type)
[](#rbac_role_permission.resource%5B0%5D)
ConnectorTool object { connector_id, tool_name, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B1%5D.connector_id)
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.
[](#rbac_role_permission.resource%5B1%5D.tool_name)
type: "connector_tool"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B1%5D.type)
[](#rbac_role_permission.resource%5B1%5D)
ConnectorScope object { connector_id, scope, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B2%5D.connector_id)
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.
[](#rbac_role_permission.resource%5B2%5D.scope)
type: "connector_scope"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B2%5D.type)
[](#rbac_role_permission.resource%5B2%5D)
Connector object { connector_id, type }
connector_id: string
ID of the connector the permission applies to.
[](#rbac_role_permission.resource%5B3%5D.connector_id)
type: "connector"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B3%5D.type)
[](#rbac_role_permission.resource%5B3%5D)
AllConnectors object { type }
type: "all_connectors"
Kind of resource the permission applies to.
[](#rbac_role_permission.resource%5B4%5D.type)
[](#rbac_role_permission.resource%5B4%5D)
[](#rbac_role_permission.resource)
type: "rbac_role_permission"
Object type.
For RBAC Role Permissions, this is always `"rbac_role_permission"`.
[](#rbac_role_permission.type)
[](#list)
has_more: boolean
Indicates whether there are more results beyond this page.
[](#list)
next_page: string
Opaque cursor for the next page. Pass as the `page` parameter on the next request.
[](#list)
List RBAC Role Permissions
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles/$ROLE_ID/permissions \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get RBAC Role
GET/v1/organizations/rbac_roles/{role_id}
Retrieve an RBAC Role by ID.
The RBAC Roles API is in beta and available to Claude Enterprise organizations only. Requests must send the `ce-user-management-2026-07-13` value in the `anthropic-beta` header.
##### Path ParametersExpand Collapse
role_id: string
ID of the RBAC Role.
[](#retrieve.role_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
RbacRole object { id, created_at, name, 2 more }
id: string
ID of the RBAC Role.
[](#rbac_role.id)
created_at: string
RFC 3339 datetime string indicating when the RBAC Role was created.
[](#rbac_role.created_at)
name: string
Name of the RBAC Role.
[](#rbac_role.name)
type: "rbac_role"
Object type.
For RBAC Roles, this is always `"rbac_role"`.
[](#rbac_role.type)
updated_at: string
RFC 3339 datetime string indicating when the RBAC Role was last updated.
[](#rbac_role.updated_at)
[](#rbac_role)
Get RBAC Role
```python
curl https://api.anthropic.com/v1/organizations/rbac_roles/$ROLE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Service accounts
# Service Accounts
##### [Create Service Account](/docs/en/api/admin/service_accounts/create)
POST/v1/organizations/service_accounts
##### [Get Service Account](/docs/en/api/admin/service_accounts/retrieve)
GET/v1/organizations/service_accounts/{service_account_id}
##### [List Service Accounts](/docs/en/api/admin/service_accounts/list)
GET/v1/organizations/service_accounts
##### [Update Service Account](/docs/en/api/admin/service_accounts/update)
POST/v1/organizations/service_accounts/{service_account_id}
##### [Archive Service Account](/docs/en/api/admin/service_accounts/archive)
POST/v1/organizations/service_accounts/{service_account_id}/archive
##### ModelsExpand Collapse
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).
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#service_account)
#### Service AccountsWorkspaces
##### [Add Workspace To Service Account](/docs/en/api/admin/service_accounts/workspaces/create)
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [List Workspaces For Service Account](/docs/en/api/admin/service_accounts/workspaces/list)
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [Remove Workspace From Service Account](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# Archive Service Account
POST/v1/organizations/service_accounts/{service_account_id}/archive
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.
Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account to archive.
[](#archive.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#archive.anthropic-beta)
##### ReturnsExpand Collapse
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).
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#service_account)
Archive Service Account
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Service Account
POST/v1/organizations/service_accounts
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`. Requires an OAuth bearer (user or WIF-minted service account token) or a Console session; Admin API keys are not accepted. 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.
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
name: string
Slug identifier (lowercase, digits, hyphens). Unique within the organization; a duplicate name returns 409.
[](#create.name)
description: optional string
Optional free-text description.
[](#create.description)
organization_role: optional "admin" or "developer"
Org-level role. Defaults to `developer`.
One of the following:
"admin"
[](#create.organization_role%5B0%5D)
"developer"
[](#create.organization_role%5B1%5D)
[](#create.organization_role)
##### ReturnsExpand Collapse
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).
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#service_account)
Create Service Account
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Service Accounts
GET/v1/organizations/service_accounts
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 ParametersExpand Collapse
include_archived: optional boolean
Include archived resources. Defaults to false.
[](#list.include_archived)
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of [ServiceAccount](/docs/en/api/admin/service_accounts#service_account) { id, archived_at, archived_by_actor_id, 8 more }
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results.
[](#list)
List Service Accounts
```python
curl https://api.anthropic.com/v1/organizations/service_accounts \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Service Account
GET/v1/organizations/service_accounts/{service_account_id}
Retrieve a service account by its ID (`svac_...`).
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account.
[](#retrieve.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
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).
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#service_account)
Get Service Account
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Service Account
POST/v1/organizations/service_accounts/{service_account_id}
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). Admin API keys are not accepted.
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account to update.
[](#update.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#update.anthropic-beta)
##### Body ParametersJSONExpand Collapse
description: optional string
Replaces the description. Omit to leave unchanged; send `null` to clear (the field is stored as an empty string).
[](#update.description)
organization_role: optional "admin" or "developer"
Replaces the org-level role. Omit or send `null` to leave unchanged.
One of the following:
"admin"
[](#update.organization_role%5B0%5D)
"developer"
[](#update.organization_role%5B1%5D)
[](#update.organization_role)
##### ReturnsExpand Collapse
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).
id: string
Tagged ID of the service account.
[](#service_account.id)
archived_at: string
If set, this service account is archived.
[](#service_account.archived_at)
archived_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that archived this service account.
[](#service_account.archived_by_actor_id)
created_at: string
When this service account was created.
[](#service_account.created_at)
created_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that created this service account.
[](#service_account.created_by_actor_id)
description: string
Optional free-text description.
[](#service_account.description)
name: string
Admin-chosen slug identifier.
[](#service_account.name)
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"
[](#service_account.organization_role%5B0%5D)
"developer"
[](#service_account.organization_role%5B1%5D)
[](#service_account.organization_role)
type: "service_account"
[](#service_account.type)
updated_at: string
When this service account was last updated.
[](#service_account.updated_at)
updated_by_actor_id: string
Tagged ID (`user_`/`svac_`) of the actor that last updated this service account.
[](#service_account.updated_by_actor_id)
[](#service_account)
Update Service Account
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Add Workspace To Service Account
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account.
[](#create.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
workspace_id: string
Tagged workspace ID to add the service account to.
[](#create.workspace_id)
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"
[](#create.workspace_role%5B0%5D)
"workspace_developer"
[](#create.workspace_role%5B1%5D)
"workspace_restricted_developer"
[](#create.workspace_role%5B2%5D)
"workspace_user"
[](#create.workspace_role%5B3%5D)
[](#create.workspace_role)
##### ReturnsExpand Collapse
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#workspace_create_response.created_by_actor_id)
implicit: boolean
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.
[](#workspace_create_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#workspace_create_response.service_account_id)
type: "service_account_workspace_member"
[](#workspace_create_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#workspace_create_response.workspace_id)
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_create_response.workspace_role%5B0%5D)
"workspace_billing"
[](#workspace_create_response.workspace_role%5B1%5D)
"workspace_developer"
[](#workspace_create_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspace_create_response.workspace_role%5B3%5D)
"workspace_user"
[](#workspace_create_response.workspace_role%5B4%5D)
[](#workspace_create_response.workspace_role)
Add Workspace To Service Account
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Remove Workspace From Service Account
DELETE/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account.
[](#delete.service_account_id)
workspace_id: string
ID of the workspace.
[](#delete.workspace_id)
##### Header ParametersExpand Collapse
"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.
[](#delete.anthropic-beta)
##### ReturnsExpand Collapse
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.
[](#workspace_delete_response.service_account_id)
type: "service_account_workspace_member_deleted"
[](#workspace_delete_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
[](#workspace_delete_response.workspace_id)
Remove Workspace From Service Account
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Workspaces
# Workspaces
##### [Add Workspace To Service Account](/docs/en/api/admin/service_accounts/workspaces/create)
POST/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [List Workspaces For Service Account](/docs/en/api/admin/service_accounts/workspaces/list)
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
##### [Remove Workspace From Service Account](/docs/en/api/admin/service_accounts/workspaces/delete)
DELETE/v1/organizations/service_accounts/{service_account_id}/workspaces/{workspace_id}
##### ModelsExpand Collapse
WorkspaceCreateResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#workspace_create_response.created_by_actor_id)
implicit: boolean
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.
[](#workspace_create_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#workspace_create_response.service_account_id)
type: "service_account_workspace_member"
[](#workspace_create_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#workspace_create_response.workspace_id)
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_create_response.workspace_role%5B0%5D)
"workspace_billing"
[](#workspace_create_response.workspace_role%5B1%5D)
"workspace_developer"
[](#workspace_create_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspace_create_response.workspace_role%5B3%5D)
"workspace_user"
[](#workspace_create_response.workspace_role%5B4%5D)
[](#workspace_create_response.workspace_role)
[](#workspace_create_response)
WorkspaceListResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#workspace_list_response.created_by_actor_id)
implicit: boolean
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.
[](#workspace_list_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#workspace_list_response.service_account_id)
type: "service_account_workspace_member"
[](#workspace_list_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#workspace_list_response.workspace_id)
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_list_response.workspace_role%5B0%5D)
"workspace_billing"
[](#workspace_list_response.workspace_role%5B1%5D)
"workspace_developer"
[](#workspace_list_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspace_list_response.workspace_role%5B3%5D)
"workspace_user"
[](#workspace_list_response.workspace_role%5B4%5D)
[](#workspace_list_response.workspace_role)
[](#workspace_list_response)
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.
[](#workspace_delete_response.service_account_id)
type: "service_account_workspace_member_deleted"
[](#workspace_delete_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
[](#workspace_delete_response.workspace_id)
[](#workspace_delete_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Workspaces For Service Account
GET/v1/organizations/service_accounts/{service_account_id}/workspaces
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; an archived service account returns an empty list.
##### Path ParametersExpand Collapse
service_account_id: string
ID of the service account.
[](#list.service_account_id)
##### Query ParametersExpand Collapse
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#workspace_list_response.created_by_actor_id)
implicit: boolean
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.
[](#workspace_list_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#workspace_list_response.service_account_id)
type: "service_account_workspace_member"
[](#workspace_list_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#workspace_list_response.workspace_id)
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_list_response.workspace_role%5B0%5D)
"workspace_billing"
[](#workspace_list_response.workspace_role%5B1%5D)
"workspace_developer"
[](#workspace_list_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspace_list_response.workspace_role%5B3%5D)
"workspace_user"
[](#workspace_list_response.workspace_role%5B4%5D)
[](#workspace_list_response.workspace_role)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results.
[](#list)
List Workspaces For Service Account
```python
curl https://api.anthropic.com/v1/organizations/service_accounts/$SERVICE_ACCOUNT_ID/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Spend limits
# Spend Limits
##### [Set Spend Limit](/docs/en/api/admin/spend_limits/create)
POST/v1/organizations/spend_limits
##### [Get Spend Limit](/docs/en/api/admin/spend_limits/retrieve)
GET/v1/organizations/spend_limits/{spend_limit_id}
##### [Delete Spend Limit](/docs/en/api/admin/spend_limits/delete)
DELETE/v1/organizations/spend_limits/{spend_limit_id}
##### [List Effective Spend Limits](/docs/en/api/admin/spend_limits/list_effective)
GET/v1/organizations/spend_limits/effective
##### ModelsExpand Collapse
SpendLimit object { id, amount, created_at, 5 more }
id: string
[](#spend_limit.id)
amount: string
[](#spend_limit.amount)
created_at: string
[](#spend_limit.created_at)
currency: string
[](#spend_limit.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit.period%5B0%5D)
"monthly"
[](#spend_limit.period%5B1%5D)
"weekly"
[](#spend_limit.period%5B2%5D)
[](#spend_limit.period)
scope: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit.scope%5B0%5D.type)
user_id: string
[](#spend_limit.scope%5B0%5D.user_id)
[](#spend_limit.scope%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit.scope%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit.scope%5B1%5D.type)
[](#spend_limit.scope%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit.scope%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit.scope%5B2%5D.type)
[](#spend_limit.scope%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit.scope%5B3%5D.service)
type: "organization_service"
[](#spend_limit.scope%5B3%5D.type)
[](#spend_limit.scope%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit.scope%5B4%5D.type)
[](#spend_limit.scope%5B4%5D)
[](#spend_limit.scope)
type: "spend_limit"
[](#spend_limit.type)
updated_at: string
[](#spend_limit.updated_at)
[](#spend_limit)
SpendSummary object { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#spend_summary.actor.deleted)
email_address: string
[](#spend_summary.actor.email_address)
name: string
[](#spend_summary.actor.name)
type: "user_actor"
[](#spend_summary.actor.type)
user_id: string
[](#spend_summary.actor.user_id)
[](#spend_summary.actor)
amount: string
[](#spend_summary.amount)
currency: string
[](#spend_summary.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_summary.period%5B0%5D)
"monthly"
[](#spend_summary.period%5B1%5D)
"weekly"
[](#spend_summary.period%5B2%5D)
[](#spend_summary.period)
period_to_date_spend: string
[](#spend_summary.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_summary.scope.type)
user_id: string
[](#spend_summary.scope.user_id)
[](#spend_summary.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_summary.source%5B0%5D.type)
user_id: string
[](#spend_summary.source%5B0%5D.user_id)
[](#spend_summary.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_summary.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_summary.source%5B1%5D.type)
[](#spend_summary.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_summary.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_summary.source%5B2%5D.type)
[](#spend_summary.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_summary.source%5B3%5D.service)
type: "organization_service"
[](#spend_summary.source%5B3%5D.type)
[](#spend_summary.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_summary.source%5B4%5D.type)
[](#spend_summary.source%5B4%5D)
[](#spend_summary.source)
spend_limit_id: string
[](#spend_summary.spend_limit_id)
[](#spend_summary)
SpendLimitDeleteResponse object { id, type }
id: string
[](#spend_limit_delete_response.id)
type: "spend_limit_deleted"
[](#spend_limit_delete_response.type)
[](#spend_limit_delete_response)
#### Spend LimitsIncrease Requests
##### [List Spend Limit Increase Requests](/docs/en/api/admin/spend_limits/increase_requests/list)
GET/v1/organizations/spend_limit_increase_requests
##### [Get Spend Limit Increase Request](/docs/en/api/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/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/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# 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 ParametersJSONExpand Collapse
amount: string
[](#create.amount)
scope: object { type, user_id }
type: "user"
[](#create.scope.type)
user_id: string
[](#create.scope.user_id)
[](#create.scope)
period: optional "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#create.period%5B0%5D)
"monthly"
[](#create.period%5B1%5D)
"weekly"
[](#create.period%5B2%5D)
[](#create.period)
##### ReturnsExpand Collapse
SpendLimit object { id, amount, created_at, 5 more }
id: string
[](#spend_limit.id)
amount: string
[](#spend_limit.amount)
created_at: string
[](#spend_limit.created_at)
currency: string
[](#spend_limit.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit.period%5B0%5D)
"monthly"
[](#spend_limit.period%5B1%5D)
"weekly"
[](#spend_limit.period%5B2%5D)
[](#spend_limit.period)
scope: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit.scope%5B0%5D.type)
user_id: string
[](#spend_limit.scope%5B0%5D.user_id)
[](#spend_limit.scope%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit.scope%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit.scope%5B1%5D.type)
[](#spend_limit.scope%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit.scope%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit.scope%5B2%5D.type)
[](#spend_limit.scope%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit.scope%5B3%5D.service)
type: "organization_service"
[](#spend_limit.scope%5B3%5D.type)
[](#spend_limit.scope%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit.scope%5B4%5D.type)
[](#spend_limit.scope%5B4%5D)
[](#spend_limit.scope)
type: "spend_limit"
[](#spend_limit.type)
updated_at: string
[](#spend_limit.updated_at)
[](#spend_limit)
Set Spend Limit
```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_OAUTH_TOKEN" \
-d '{
"amount": "50000",
"scope": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"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_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# 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 ParametersExpand Collapse
spend_limit_id: string
ID of the Spend Limit.
[](#delete.spend_limit_id)
##### ReturnsExpand Collapse
id: string
[](#spend_limit_delete_response.id)
type: "spend_limit_deleted"
[](#spend_limit_delete_response.type)
Delete Spend Limit
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Increase requests
# Increase Requests
##### [List Spend Limit Increase Requests](/docs/en/api/admin/spend_limits/increase_requests/list)
GET/v1/organizations/spend_limit_increase_requests
##### [Get Spend Limit Increase Request](/docs/en/api/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/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/admin/spend_limits/increase_requests/deny)
POST/v1/organizations/spend_limit_increase_requests/{spend_limit_increase_request_id}/deny
##### ModelsExpand Collapse
SpendLimitIncreaseRequest object { id, actor, created_at, 6 more }
id: string
[](#spend_limit_increase_request.id)
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
[](#spend_limit_increase_request.actor.deleted)
email_address: string
[](#spend_limit_increase_request.actor.email_address)
name: string
[](#spend_limit_increase_request.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.actor.type)
user_id: string
[](#spend_limit_increase_request.actor.user_id)
[](#spend_limit_increase_request.actor)
created_at: string
[](#spend_limit_increase_request.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.period%5B2%5D)
[](#spend_limit_increase_request.period)
resolved_at: string
[](#spend_limit_increase_request.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#spend_limit_increase_request.resolved_by%5B0%5D.deleted)
email_address: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.email_address)
name: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.name)
type: "user_actor"
[](#spend_limit_increase_request.resolved_by%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.user_id)
[](#spend_limit_increase_request.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#spend_limit_increase_request.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#spend_limit_increase_request.resolved_by%5B1%5D.type)
[](#spend_limit_increase_request.resolved_by%5B1%5D)
[](#spend_limit_increase_request.resolved_by)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#spend_limit_increase_request.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#spend_limit_increase_request.status%5B0%5D)
"denied"
[](#spend_limit_increase_request.status%5B1%5D)
"pending"
[](#spend_limit_increase_request.status%5B2%5D)
[](#spend_limit_increase_request.status)
type: "spend_limit_increase_request"
[](#spend_limit_increase_request.type)
[](#spend_limit_increase_request)
IncreaseRequestApproveResponse object { id, actor, created_at, 7 more }
id: string
[](#increase_request_approve_response.id)
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
[](#increase_request_approve_response.actor.deleted)
email_address: string
[](#increase_request_approve_response.actor.email_address)
name: string
[](#increase_request_approve_response.actor.name)
type: "user_actor"
[](#increase_request_approve_response.actor.type)
user_id: string
[](#increase_request_approve_response.actor.user_id)
[](#increase_request_approve_response.actor)
created_at: string
[](#increase_request_approve_response.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.period%5B2%5D)
[](#increase_request_approve_response.period)
resolved_at: string
[](#increase_request_approve_response.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#increase_request_approve_response.resolved_by%5B0%5D.deleted)
email_address: string
[](#increase_request_approve_response.resolved_by%5B0%5D.email_address)
name: string
[](#increase_request_approve_response.resolved_by%5B0%5D.name)
type: "user_actor"
[](#increase_request_approve_response.resolved_by%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.resolved_by%5B0%5D.user_id)
[](#increase_request_approve_response.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#increase_request_approve_response.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#increase_request_approve_response.resolved_by%5B1%5D.type)
[](#increase_request_approve_response.resolved_by%5B1%5D)
[](#increase_request_approve_response.resolved_by)
spend_limit: [SpendLimit](/docs/en/api/admin/spend_limits#spend_limit) { id, amount, created_at, 5 more }
id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.id)
amount: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.amount)
created_at: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.created_at)
currency: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period)
scope: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D.user_id)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D.seat_tier)
type: "seat_tier"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D)
OrganizationService object { service, type }
service: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D.service)
type: "organization_service"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D)
Organization object { type }
type: "organization"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B4%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B4%5D)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope)
type: "spend_limit"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.type)
updated_at: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.updated_at)
[](#increase_request_approve_response.spend_limit)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#increase_request_approve_response.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#increase_request_approve_response.status%5B0%5D)
"denied"
[](#increase_request_approve_response.status%5B1%5D)
"pending"
[](#increase_request_approve_response.status%5B2%5D)
[](#increase_request_approve_response.status)
type: "spend_limit_increase_request"
[](#increase_request_approve_response.type)
[](#increase_request_approve_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Approve
# 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 ParametersExpand Collapse
spend_limit_increase_request_id: string
ID of the spend limit increase request.
[](#approve.spend_limit_increase_request_id)
##### Body ParametersJSONExpand Collapse
amount: string
New per-user spend limit as a non-negative integer decimal string (minor units).
[](#approve.amount)
period: optional "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#approve.period%5B0%5D)
"monthly"
[](#approve.period%5B1%5D)
"weekly"
[](#approve.period%5B2%5D)
[](#approve.period)
suppress_notification: optional boolean
[](#approve.suppress_notification)
##### ReturnsExpand Collapse
id: string
[](#increase_request_approve_response.id)
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
[](#increase_request_approve_response.actor.deleted)
email_address: string
[](#increase_request_approve_response.actor.email_address)
name: string
[](#increase_request_approve_response.actor.name)
type: "user_actor"
[](#increase_request_approve_response.actor.type)
user_id: string
[](#increase_request_approve_response.actor.user_id)
[](#increase_request_approve_response.actor)
created_at: string
[](#increase_request_approve_response.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.period%5B2%5D)
[](#increase_request_approve_response.period)
resolved_at: string
[](#increase_request_approve_response.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#increase_request_approve_response.resolved_by%5B0%5D.deleted)
email_address: string
[](#increase_request_approve_response.resolved_by%5B0%5D.email_address)
name: string
[](#increase_request_approve_response.resolved_by%5B0%5D.name)
type: "user_actor"
[](#increase_request_approve_response.resolved_by%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.resolved_by%5B0%5D.user_id)
[](#increase_request_approve_response.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#increase_request_approve_response.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#increase_request_approve_response.resolved_by%5B1%5D.type)
[](#increase_request_approve_response.resolved_by%5B1%5D)
[](#increase_request_approve_response.resolved_by)
spend_limit: [SpendLimit](/docs/en/api/admin/spend_limits#spend_limit) { id, amount, created_at, 5 more }
id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.id)
amount: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.amount)
created_at: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.created_at)
currency: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.period)
scope: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D.user_id)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D.seat_tier)
type: "seat_tier"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B2%5D)
OrganizationService object { service, type }
service: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D.service)
type: "organization_service"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B3%5D)
Organization object { type }
type: "organization"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B4%5D.type)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope%5B4%5D)
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.scope)
type: "spend_limit"
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.type)
updated_at: string
[](#increase_request_approve_response.spend_limit%20%2B%20(resource)%20admin.spend_limits.updated_at)
[](#increase_request_approve_response.spend_limit)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#increase_request_approve_response.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#increase_request_approve_response.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#increase_request_approve_response.status%5B0%5D)
"denied"
[](#increase_request_approve_response.status%5B1%5D)
"pending"
[](#increase_request_approve_response.status%5B2%5D)
[](#increase_request_approve_response.status)
type: "spend_limit_increase_request"
[](#increase_request_approve_response.type)
Approve Spend Limit Increase Request
```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_OAUTH_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_id"
},
"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_id"
},
"spend_limit": {
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"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_id"
},
"spend_limit": {
"id": "id",
"amount": "50000",
"created_at": "2019-12-27T18:11:19.117Z",
"currency": "USD",
"period": "monthly",
"scope": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Deny
# 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 ParametersExpand Collapse
spend_limit_increase_request_id: string
ID of the spend limit increase request.
[](#deny.spend_limit_increase_request_id)
##### Body ParametersJSONExpand Collapse
suppress_notification: optional boolean
[](#deny.suppress_notification)
##### ReturnsExpand Collapse
SpendLimitIncreaseRequest object { id, actor, created_at, 6 more }
id: string
[](#spend_limit_increase_request.id)
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
[](#spend_limit_increase_request.actor.deleted)
email_address: string
[](#spend_limit_increase_request.actor.email_address)
name: string
[](#spend_limit_increase_request.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.actor.type)
user_id: string
[](#spend_limit_increase_request.actor.user_id)
[](#spend_limit_increase_request.actor)
created_at: string
[](#spend_limit_increase_request.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.period%5B2%5D)
[](#spend_limit_increase_request.period)
resolved_at: string
[](#spend_limit_increase_request.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#spend_limit_increase_request.resolved_by%5B0%5D.deleted)
email_address: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.email_address)
name: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.name)
type: "user_actor"
[](#spend_limit_increase_request.resolved_by%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.user_id)
[](#spend_limit_increase_request.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#spend_limit_increase_request.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#spend_limit_increase_request.resolved_by%5B1%5D.type)
[](#spend_limit_increase_request.resolved_by%5B1%5D)
[](#spend_limit_increase_request.resolved_by)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#spend_limit_increase_request.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#spend_limit_increase_request.status%5B0%5D)
"denied"
[](#spend_limit_increase_request.status%5B1%5D)
"pending"
[](#spend_limit_increase_request.status%5B2%5D)
[](#spend_limit_increase_request.status)
type: "spend_limit_increase_request"
[](#spend_limit_increase_request.type)
[](#spend_limit_increase_request)
Deny Spend Limit Increase Request
```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_OAUTH_TOKEN" \
-d '{}'
```
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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 ParametersExpand Collapse
actor_ids: optional array of string
Filter by requester, as `user_...` tagged IDs.
[](#list.actor_ids)
limit: optional number
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
status: optional array of "approved" or "denied" or "pending"
Filter by status. Omit to return all.
One of the following:
"approved"
[](#list.status.items%5B0%5D)
"denied"
[](#list.status.items%5B1%5D)
"pending"
[](#list.status.items%5B2%5D)
[](#list.status)
##### ReturnsExpand Collapse
data: array of [SpendLimitIncreaseRequest](/docs/en/api/admin/spend_limits/increase_requests#spend_limit_increase_request) { id, actor, created_at, 6 more }
id: string
[](#spend_limit_increase_request.id)
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
[](#spend_limit_increase_request.actor.deleted)
email_address: string
[](#spend_limit_increase_request.actor.email_address)
name: string
[](#spend_limit_increase_request.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.actor.type)
user_id: string
[](#spend_limit_increase_request.actor.user_id)
[](#spend_limit_increase_request.actor)
created_at: string
[](#spend_limit_increase_request.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.period%5B2%5D)
[](#spend_limit_increase_request.period)
resolved_at: string
[](#spend_limit_increase_request.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#spend_limit_increase_request.resolved_by%5B0%5D.deleted)
email_address: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.email_address)
name: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.name)
type: "user_actor"
[](#spend_limit_increase_request.resolved_by%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.user_id)
[](#spend_limit_increase_request.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#spend_limit_increase_request.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#spend_limit_increase_request.resolved_by%5B1%5D.type)
[](#spend_limit_increase_request.resolved_by%5B1%5D)
[](#spend_limit_increase_request.resolved_by)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#spend_limit_increase_request.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#spend_limit_increase_request.status%5B0%5D)
"denied"
[](#spend_limit_increase_request.status%5B1%5D)
"pending"
[](#spend_limit_increase_request.status%5B2%5D)
[](#spend_limit_increase_request.status)
type: "spend_limit_increase_request"
[](#spend_limit_increase_request.type)
[](#list)
next_page: string
[](#list)
List Spend Limit Increase Requests
```python
curl https://api.anthropic.com/v1/organizations/spend_limit_increase_requests \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# 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 ParametersExpand Collapse
spend_limit_increase_request_id: string
ID of the spend limit increase request.
[](#retrieve.spend_limit_increase_request_id)
##### ReturnsExpand Collapse
SpendLimitIncreaseRequest object { id, actor, created_at, 6 more }
id: string
[](#spend_limit_increase_request.id)
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
[](#spend_limit_increase_request.actor.deleted)
email_address: string
[](#spend_limit_increase_request.actor.email_address)
name: string
[](#spend_limit_increase_request.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.actor.type)
user_id: string
[](#spend_limit_increase_request.actor.user_id)
[](#spend_limit_increase_request.actor)
created_at: string
[](#spend_limit_increase_request.created_at)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.period%5B2%5D)
[](#spend_limit_increase_request.period)
resolved_at: string
[](#spend_limit_increase_request.resolved_at)
resolved_by: object { deleted, email_address, name, 2 more } or object { scoped_api_key_id, type }
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
[](#spend_limit_increase_request.resolved_by%5B0%5D.deleted)
email_address: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.email_address)
name: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.name)
type: "user_actor"
[](#spend_limit_increase_request.resolved_by%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.resolved_by%5B0%5D.user_id)
[](#spend_limit_increase_request.resolved_by%5B0%5D)
ScopedAPIKeyActor object { scoped_api_key_id, type }
A scoped Admin API key acting on behalf of the organization.
scoped_api_key_id: string
[](#spend_limit_increase_request.resolved_by%5B1%5D.scoped_api_key_id)
type: "scoped_api_key_actor"
[](#spend_limit_increase_request.resolved_by%5B1%5D.type)
[](#spend_limit_increase_request.resolved_by%5B1%5D)
[](#spend_limit_increase_request.resolved_by)
spend_summary: [SpendSummary](/docs/en/api/admin/spend_limits#spend_summary) { actor, amount, currency, 5 more }
Per-member effective-limit report row (GET /spend_limits/effective).
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
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.deleted)
email_address: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.email_address)
name: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.name)
type: "user_actor"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.actor)
amount: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.amount)
currency: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B0%5D)
"monthly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B1%5D)
"weekly"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period%5B2%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period)
period_to_date_spend: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.type)
user_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D.user_id)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.service)
type: "organization_service"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D.type)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source%5B4%5D)
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.source)
spend_limit_id: string
[](#spend_limit_increase_request.spend_summary%20%2B%20(resource)%20admin.spend_limits.spend_limit_id)
[](#spend_limit_increase_request.spend_summary)
status: "approved" or "denied" or "pending"
One of the following:
"approved"
[](#spend_limit_increase_request.status%5B0%5D)
"denied"
[](#spend_limit_increase_request.status%5B1%5D)
"pending"
[](#spend_limit_increase_request.status%5B2%5D)
[](#spend_limit_increase_request.status)
type: "spend_limit_increase_request"
[](#spend_limit_increase_request.type)
[](#spend_limit_increase_request)
Get Spend Limit Increase Request
```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_OAUTH_TOKEN"
```
Response 200
```python
{
"id": "id",
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"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_id"
},
"spend_summary": {
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List effective
# 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 ParametersExpand Collapse
limit: optional number
[](#list_effective.limit)
page: optional string
[](#list_effective.page)
period: optional array of string
[](#list_effective.period)
user_ids: optional array of string
[](#list_effective.user_ids)
##### ReturnsExpand Collapse
data: array of [SpendSummary](/docs/en/api/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
[](#spend_summary.actor.deleted)
email_address: string
[](#spend_summary.actor.email_address)
name: string
[](#spend_summary.actor.name)
type: "user_actor"
[](#spend_summary.actor.type)
user_id: string
[](#spend_summary.actor.user_id)
[](#spend_summary.actor)
amount: string
[](#spend_summary.amount)
currency: string
[](#spend_summary.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_summary.period%5B0%5D)
"monthly"
[](#spend_summary.period%5B1%5D)
"weekly"
[](#spend_summary.period%5B2%5D)
[](#spend_summary.period)
period_to_date_spend: string
[](#spend_summary.period_to_date_spend)
scope: object { type, user_id }
type: "user"
[](#spend_summary.scope.type)
user_id: string
[](#spend_summary.scope.user_id)
[](#spend_summary.scope)
source: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_summary.source%5B0%5D.type)
user_id: string
[](#spend_summary.source%5B0%5D.user_id)
[](#spend_summary.source%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_summary.source%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_summary.source%5B1%5D.type)
[](#spend_summary.source%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_summary.source%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_summary.source%5B2%5D.type)
[](#spend_summary.source%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_summary.source%5B3%5D.service)
type: "organization_service"
[](#spend_summary.source%5B3%5D.type)
[](#spend_summary.source%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_summary.source%5B4%5D.type)
[](#spend_summary.source%5B4%5D)
[](#spend_summary.source)
spend_limit_id: string
[](#spend_summary.spend_limit_id)
[](#list_effective)
next_page: string
[](#list_effective)
List Effective Spend Limits
```python
curl https://api.anthropic.com/v1/organizations/spend_limits/effective \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"actor": {
"deleted": true,
"email_address": "email_address",
"name": "name",
"type": "user_actor",
"user_id": "user_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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_id"
},
"amount": "50000",
"currency": "USD",
"period": "monthly",
"period_to_date_spend": "period_to_date_spend",
"scope": {
"type": "user",
"user_id": "user_id"
},
"source": {
"type": "user",
"user_id": "user_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Spend Limit
GET/v1/organizations/spend_limits/{spend_limit_id}
Retrieve a spend limit by ID.
##### Path ParametersExpand Collapse
spend_limit_id: string
ID of the Spend Limit.
[](#retrieve.spend_limit_id)
##### ReturnsExpand Collapse
SpendLimit object { id, amount, created_at, 5 more }
id: string
[](#spend_limit.id)
amount: string
[](#spend_limit.amount)
created_at: string
[](#spend_limit.created_at)
currency: string
[](#spend_limit.currency)
period: "daily" or "monthly" or "weekly"
One of the following:
"daily"
[](#spend_limit.period%5B0%5D)
"monthly"
[](#spend_limit.period%5B1%5D)
"weekly"
[](#spend_limit.period%5B2%5D)
[](#spend_limit.period)
scope: object { type, user_id } or object { seat_tier, type } or object { rbac_group_id, type } or 2 more
One of the following:
User object { type, user_id }
type: "user"
[](#spend_limit.scope%5B0%5D.type)
user_id: string
[](#spend_limit.scope%5B0%5D.user_id)
[](#spend_limit.scope%5B0%5D)
SeatTier object { seat_tier, type }
seat_tier: string
[](#spend_limit.scope%5B1%5D.seat_tier)
type: "seat_tier"
[](#spend_limit.scope%5B1%5D.type)
[](#spend_limit.scope%5B1%5D)
RbacGroup object { rbac_group_id, type }
rbac_group_id: string
[](#spend_limit.scope%5B2%5D.rbac_group_id)
type: "rbac_group"
[](#spend_limit.scope%5B2%5D.type)
[](#spend_limit.scope%5B2%5D)
OrganizationService object { service, type }
service: string
[](#spend_limit.scope%5B3%5D.service)
type: "organization_service"
[](#spend_limit.scope%5B3%5D.type)
[](#spend_limit.scope%5B3%5D)
Organization object { type }
type: "organization"
[](#spend_limit.scope%5B4%5D.type)
[](#spend_limit.scope%5B4%5D)
[](#spend_limit.scope)
type: "spend_limit"
[](#spend_limit.type)
updated_at: string
[](#spend_limit.updated_at)
[](#spend_limit)
Get Spend Limit
```python
curl https://api.anthropic.com/v1/organizations/spend_limits/$SPEND_LIMIT_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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_id"
},
"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_id"
},
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Usage report
# Usage Report
##### [Get Messages Usage Report](/docs/en/api/admin/usage_report/retrieve_messages)
GET/v1/organizations/usage_report/messages
##### [Get Claude Code Usage Report](/docs/en/api/admin/usage_report/retrieve_claude_code)
GET/v1/organizations/usage_report/claude_code
##### ModelsExpand Collapse
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.
One of the following:
ClaudeCodeUserActor object { email_address, type }
email_address: string
Email address of the user who performed Claude Code actions.
[](#claude_code_usage_report.data.items.actor%5B0%5D.email_address)
type: "user_actor"
[](#claude_code_usage_report.data.items.actor%5B0%5D.type)
[](#claude_code_usage_report.data.items.actor%5B0%5D)
ClaudeCodeAPIActor object { api_key_name, type }
api_key_name: string
Name of the API key used to perform Claude Code actions.
[](#claude_code_usage_report.data.items.actor%5B1%5D.api_key_name)
type: "api_actor"
[](#claude_code_usage_report.data.items.actor%5B1%5D.type)
[](#claude_code_usage_report.data.items.actor%5B1%5D)
[](#claude_code_usage_report.data.items.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.
[](#claude_code_usage_report.data.items.core_metrics.commits_by_claude_code)
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.
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code.added)
removed: number
Total number of lines of code removed across all files by Claude Code.
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code.removed)
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code)
num_sessions: number
Number of distinct Claude Code sessions initiated by this actor.
[](#claude_code_usage_report.data.items.core_metrics.num_sessions)
pull_requests_by_claude_code: number
Number of pull requests created through Claude Code's PR functionality.
[](#claude_code_usage_report.data.items.core_metrics.pull_requests_by_claude_code)
[](#claude_code_usage_report.data.items.core_metrics)
customer_type: "api" or "subscription"
Type of customer account (api for API customers, subscription for Pro/Team customers).
One of the following:
"api"
[](#claude_code_usage_report.data.items.customer_type%5B0%5D)
"subscription"
[](#claude_code_usage_report.data.items.customer_type%5B1%5D)
[](#claude_code_usage_report.data.items.customer_type)
date: string
UTC date for the usage metrics in YYYY-MM-DD format.
[](#claude_code_usage_report.data.items.date)
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).
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost.amount)
currency: string
Currency code for the estimated cost (e.g., 'USD').
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost.currency)
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost)
model: string
Name of the AI model used for Claude Code interactions.
[](#claude_code_usage_report.data.items.model_breakdown.items.model)
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.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.cache_creation)
cache_read: number
Number of cache read tokens consumed by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.cache_read)
input: number
Number of input tokens consumed by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.input)
output: number
Number of output tokens generated by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.output)
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens)
[](#claude_code_usage_report.data.items.model_breakdown)
organization_id: string
ID of the organization that owns the Claude Code usage.
[](#claude_code_usage_report.data.items.organization_id)
terminal_type: string
Type of terminal or environment where Claude Code was used.
[](#claude_code_usage_report.data.items.terminal_type)
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.
[](#claude_code_usage_report.data.items.tool_actions.items.accepted)
rejected: number
Number of tool action proposals that the user rejected.
[](#claude_code_usage_report.data.items.tool_actions.items.rejected)
[](#claude_code_usage_report.data.items.tool_actions)
subscription_type: optional "enterprise" or "team"
Subscription tier for subscription customers. `null` for API customers.
One of the following:
"enterprise"
[](#claude_code_usage_report.data.items.subscription_type%5B0%5D)
"team"
[](#claude_code_usage_report.data.items.subscription_type%5B1%5D)
[](#claude_code_usage_report.data.items.subscription_type)
[](#claude_code_usage_report.data)
has_more: boolean
True if there are more records available beyond the current page.
[](#claude_code_usage_report.has_more)
next_page: string
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
[](#claude_code_usage_report.next_page)
[](#claude_code_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.
[](#messages_usage_report.data.items.ending_at)
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.
[](#messages_usage_report.data.items.results.items.account_id)
api_key_id: string
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
[](#messages_usage_report.data.items.results.items.api_key_id)
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.
[](#messages_usage_report.data.items.results.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#messages_usage_report.data.items.results.items.cache_creation.ephemeral_5m_input_tokens)
[](#messages_usage_report.data.items.results.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#messages_usage_report.data.items.results.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
Context window used. `null` if not grouping by context window.
One of the following:
"0-200k"
[](#messages_usage_report.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#messages_usage_report.data.items.results.items.context_window%5B1%5D)
[](#messages_usage_report.data.items.results.items.context_window)
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.
[](#messages_usage_report.data.items.results.items.inference_geo)
model: string
Model used. `null` if not grouping by model.
[](#messages_usage_report.data.items.results.items.model)
output_tokens: number
The number of output tokens generated.
[](#messages_usage_report.data.items.results.items.output_tokens)
server_tool_use: object { web_search_requests }
Server-side tool usage metrics.
web_search_requests: number
The number of web search requests made.
[](#messages_usage_report.data.items.results.items.server_tool_use.web_search_requests)
[](#messages_usage_report.data.items.results.items.server_tool_use)
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.
[](#messages_usage_report.data.items.results.items.service_account_id)
service_tier: "batch" or "flex" or "flex_discount" or 3 more
Service tier used. `null` if not grouping by service tier.
One of the following:
"batch"
[](#messages_usage_report.data.items.results.items.service_tier%5B0%5D)
"flex"
[](#messages_usage_report.data.items.results.items.service_tier%5B1%5D)
"flex_discount"
[](#messages_usage_report.data.items.results.items.service_tier%5B2%5D)
"priority"
[](#messages_usage_report.data.items.results.items.service_tier%5B3%5D)
"priority_on_demand"
[](#messages_usage_report.data.items.results.items.service_tier%5B4%5D)
"standard"
[](#messages_usage_report.data.items.results.items.service_tier%5B5%5D)
[](#messages_usage_report.data.items.results.items.service_tier)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#messages_usage_report.data.items.results.items.uncached_input_tokens)
workspace_id: string
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
[](#messages_usage_report.data.items.results.items.workspace_id)
[](#messages_usage_report.data.items.results)
starting_at: string
Start of the time bucket (inclusive) in RFC 3339 format.
[](#messages_usage_report.data.items.starting_at)
[](#messages_usage_report.data)
has_more: boolean
Indicates if there are more results.
[](#messages_usage_report.has_more)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#messages_usage_report.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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve claude code
# 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 ParametersExpand Collapse
starting_at: string
UTC date in YYYY-MM-DD format. Returns metrics for this single day only.
[](#retrieve_claude_code.starting_at)
limit: optional number
Number of records per page (default: 20, max: 1000).
[](#retrieve_claude_code.limit)
page: optional string
Opaque cursor token from previous response's `next_page` field.
[](#retrieve_claude_code.page)
##### ReturnsExpand Collapse
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.
One of the following:
ClaudeCodeUserActor object { email_address, type }
email_address: string
Email address of the user who performed Claude Code actions.
[](#claude_code_usage_report.data.items.actor%5B0%5D.email_address)
type: "user_actor"
[](#claude_code_usage_report.data.items.actor%5B0%5D.type)
[](#claude_code_usage_report.data.items.actor%5B0%5D)
ClaudeCodeAPIActor object { api_key_name, type }
api_key_name: string
Name of the API key used to perform Claude Code actions.
[](#claude_code_usage_report.data.items.actor%5B1%5D.api_key_name)
type: "api_actor"
[](#claude_code_usage_report.data.items.actor%5B1%5D.type)
[](#claude_code_usage_report.data.items.actor%5B1%5D)
[](#claude_code_usage_report.data.items.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.
[](#claude_code_usage_report.data.items.core_metrics.commits_by_claude_code)
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.
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code.added)
removed: number
Total number of lines of code removed across all files by Claude Code.
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code.removed)
[](#claude_code_usage_report.data.items.core_metrics.lines_of_code)
num_sessions: number
Number of distinct Claude Code sessions initiated by this actor.
[](#claude_code_usage_report.data.items.core_metrics.num_sessions)
pull_requests_by_claude_code: number
Number of pull requests created through Claude Code's PR functionality.
[](#claude_code_usage_report.data.items.core_metrics.pull_requests_by_claude_code)
[](#claude_code_usage_report.data.items.core_metrics)
customer_type: "api" or "subscription"
Type of customer account (api for API customers, subscription for Pro/Team customers).
One of the following:
"api"
[](#claude_code_usage_report.data.items.customer_type%5B0%5D)
"subscription"
[](#claude_code_usage_report.data.items.customer_type%5B1%5D)
[](#claude_code_usage_report.data.items.customer_type)
date: string
UTC date for the usage metrics in YYYY-MM-DD format.
[](#claude_code_usage_report.data.items.date)
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).
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost.amount)
currency: string
Currency code for the estimated cost (e.g., 'USD').
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost.currency)
[](#claude_code_usage_report.data.items.model_breakdown.items.estimated_cost)
model: string
Name of the AI model used for Claude Code interactions.
[](#claude_code_usage_report.data.items.model_breakdown.items.model)
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.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.cache_creation)
cache_read: number
Number of cache read tokens consumed by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.cache_read)
input: number
Number of input tokens consumed by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.input)
output: number
Number of output tokens generated by this model.
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens.output)
[](#claude_code_usage_report.data.items.model_breakdown.items.tokens)
[](#claude_code_usage_report.data.items.model_breakdown)
organization_id: string
ID of the organization that owns the Claude Code usage.
[](#claude_code_usage_report.data.items.organization_id)
terminal_type: string
Type of terminal or environment where Claude Code was used.
[](#claude_code_usage_report.data.items.terminal_type)
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.
[](#claude_code_usage_report.data.items.tool_actions.items.accepted)
rejected: number
Number of tool action proposals that the user rejected.
[](#claude_code_usage_report.data.items.tool_actions.items.rejected)
[](#claude_code_usage_report.data.items.tool_actions)
subscription_type: optional "enterprise" or "team"
Subscription tier for subscription customers. `null` for API customers.
One of the following:
"enterprise"
[](#claude_code_usage_report.data.items.subscription_type%5B0%5D)
"team"
[](#claude_code_usage_report.data.items.subscription_type%5B1%5D)
[](#claude_code_usage_report.data.items.subscription_type)
[](#claude_code_usage_report.data)
has_more: boolean
True if there are more records available beyond the current page.
[](#claude_code_usage_report.has_more)
next_page: string
Opaque cursor token for fetching the next page of results, or null if no more pages are available.
[](#claude_code_usage_report.next_page)
[](#claude_code_usage_report)
Get Claude Code Usage Report
```python
curl https://api.anthropic.com/v1/organizations/usage_report/claude_code \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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",
"model_breakdown": [
{
"estimated_cost": {
"amount": 186,
"currency": "USD"
},
"model": "claude-sonnet-4-20250514",
"tokens": {
"cache_creation": 2340,
"cache_read": 8790,
"input": 45230,
"output": 12450
}
},
{
"estimated_cost": {
"amount": 42,
"currency": "USD"
},
"model": "claude-3-5-haiku-20241022",
"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",
"model_breakdown": [
{
"estimated_cost": {
"amount": 186,
"currency": "USD"
},
"model": "claude-sonnet-4-20250514",
"tokens": {
"cache_creation": 2340,
"cache_read": 8790,
"input": 45230,
"output": 12450
}
},
{
"estimated_cost": {
"amount": 42,
"currency": "USD"
},
"model": "claude-3-5-haiku-20241022",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve messages
# Get Messages Usage Report
GET/v1/organizations/usage_report/messages
Get Messages Usage Report
##### Query ParametersExpand Collapse
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.
[](#retrieve_messages.starting_at)
account_ids: optional array of string
Restrict usage returned to the specified user account ID(s).
[](#retrieve_messages.account_ids)
api_key_ids: optional array of string
Restrict usage returned to the specified API key ID(s).
[](#retrieve_messages.api_key_ids)
bucket_width: optional "1d" or "1h" or "1m"
Time granularity of the response data.
One of the following:
"1d"
[](#retrieve_messages.bucket_width%5B0%5D)
"1h"
[](#retrieve_messages.bucket_width%5B1%5D)
"1m"
[](#retrieve_messages.bucket_width%5B2%5D)
[](#retrieve_messages.bucket_width)
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"
[](#retrieve_messages.context_window.items%5B0%5D)
"200k-1M"
[](#retrieve_messages.context_window.items%5B1%5D)
[](#retrieve_messages.context_window)
ending_at: optional string
Time buckets that end before this RFC 3339 timestamp will be returned.
[](#retrieve_messages.ending_at)
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"
[](#retrieve_messages.group_by.items%5B0%5D)
"api_key_id"
[](#retrieve_messages.group_by.items%5B1%5D)
"context_window"
[](#retrieve_messages.group_by.items%5B2%5D)
"inference_geo"
[](#retrieve_messages.group_by.items%5B3%5D)
"model"
[](#retrieve_messages.group_by.items%5B4%5D)
"service_account_id"
[](#retrieve_messages.group_by.items%5B5%5D)
"service_tier"
[](#retrieve_messages.group_by.items%5B6%5D)
"speed"
[](#retrieve_messages.group_by.items%5B7%5D)
"workspace_id"
[](#retrieve_messages.group_by.items%5B8%5D)
[](#retrieve_messages.group_by)
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"
[](#retrieve_messages.inference_geos.items%5B0%5D)
"not_available"
[](#retrieve_messages.inference_geos.items%5B1%5D)
"us"
[](#retrieve_messages.inference_geos.items%5B2%5D)
[](#retrieve_messages.inference_geos)
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
[](#retrieve_messages.limit)
models: optional array of string
Restrict usage returned to the specified model(s).
[](#retrieve_messages.models)
page: optional string
Optionally set to the `next_page` token from the previous response.
[](#retrieve_messages.page)
service_account_ids: optional array of string
Restrict usage returned to the specified service account ID(s).
[](#retrieve_messages.service_account_ids)
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"
[](#retrieve_messages.service_tiers.items%5B0%5D)
"flex"
[](#retrieve_messages.service_tiers.items%5B1%5D)
"flex_discount"
[](#retrieve_messages.service_tiers.items%5B2%5D)
"priority"
[](#retrieve_messages.service_tiers.items%5B3%5D)
"priority_on_demand"
[](#retrieve_messages.service_tiers.items%5B4%5D)
"standard"
[](#retrieve_messages.service_tiers.items%5B5%5D)
[](#retrieve_messages.service_tiers)
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"
[](#retrieve_messages.speeds.items%5B0%5D)
"standard"
[](#retrieve_messages.speeds.items%5B1%5D)
[](#retrieve_messages.speeds)
workspace_ids: optional array of string
Restrict usage returned to the specified workspace ID(s).
[](#retrieve_messages.workspace_ids)
##### Header ParametersExpand Collapse
"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.
[](#retrieve_messages.anthropic-beta)
##### ReturnsExpand Collapse
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.
[](#messages_usage_report.data.items.ending_at)
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.
[](#messages_usage_report.data.items.results.items.account_id)
api_key_id: string
ID of the API key used. `null` if not grouping by API key or for usage in the Anthropic Console.
[](#messages_usage_report.data.items.results.items.api_key_id)
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.
[](#messages_usage_report.data.items.results.items.cache_creation.ephemeral_1h_input_tokens)
ephemeral_5m_input_tokens: number
The number of input tokens used to create the 5 minute cache entry.
[](#messages_usage_report.data.items.results.items.cache_creation.ephemeral_5m_input_tokens)
[](#messages_usage_report.data.items.results.items.cache_creation)
cache_read_input_tokens: number
The number of input tokens read from the cache.
[](#messages_usage_report.data.items.results.items.cache_read_input_tokens)
context_window: "0-200k" or "200k-1M"
Context window used. `null` if not grouping by context window.
One of the following:
"0-200k"
[](#messages_usage_report.data.items.results.items.context_window%5B0%5D)
"200k-1M"
[](#messages_usage_report.data.items.results.items.context_window%5B1%5D)
[](#messages_usage_report.data.items.results.items.context_window)
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.
[](#messages_usage_report.data.items.results.items.inference_geo)
model: string
Model used. `null` if not grouping by model.
[](#messages_usage_report.data.items.results.items.model)
output_tokens: number
The number of output tokens generated.
[](#messages_usage_report.data.items.results.items.output_tokens)
server_tool_use: object { web_search_requests }
Server-side tool usage metrics.
web_search_requests: number
The number of web search requests made.
[](#messages_usage_report.data.items.results.items.server_tool_use.web_search_requests)
[](#messages_usage_report.data.items.results.items.server_tool_use)
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.
[](#messages_usage_report.data.items.results.items.service_account_id)
service_tier: "batch" or "flex" or "flex_discount" or 3 more
Service tier used. `null` if not grouping by service tier.
One of the following:
"batch"
[](#messages_usage_report.data.items.results.items.service_tier%5B0%5D)
"flex"
[](#messages_usage_report.data.items.results.items.service_tier%5B1%5D)
"flex_discount"
[](#messages_usage_report.data.items.results.items.service_tier%5B2%5D)
"priority"
[](#messages_usage_report.data.items.results.items.service_tier%5B3%5D)
"priority_on_demand"
[](#messages_usage_report.data.items.results.items.service_tier%5B4%5D)
"standard"
[](#messages_usage_report.data.items.results.items.service_tier%5B5%5D)
[](#messages_usage_report.data.items.results.items.service_tier)
uncached_input_tokens: number
The number of uncached input tokens processed.
[](#messages_usage_report.data.items.results.items.uncached_input_tokens)
workspace_id: string
ID of the Workspace used. `null` if not grouping by workspace or for the default workspace.
[](#messages_usage_report.data.items.results.items.workspace_id)
[](#messages_usage_report.data.items.results)
starting_at: string
Start of the time bucket (inclusive) in RFC 3339 format.
[](#messages_usage_report.data.items.starting_at)
[](#messages_usage_report.data)
has_more: boolean
Indicates if there are more results.
[](#messages_usage_report.has_more)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#messages_usage_report.next_page)
[](#messages_usage_report)
Get Messages Usage Report
```python
curl https://api.anthropic.com/v1/organizations/usage_report/messages \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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-4-6",
"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": "2019-12-27T18:11:19.117Z"
}
```
##### 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-4-6",
"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": "2019-12-27T18:11:19.117Z"
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Remove User
DELETE/v1/organizations/users/{user_id}
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Path ParametersExpand Collapse
user_id: string
ID of the User.
[](#delete.user_id)
##### ReturnsExpand Collapse
id: string
ID of the User.
[](#user_delete_response.id)
type: "user_deleted"
Deleted object type.
For Users, this is always `"user_deleted"`.
[](#user_delete_response.type)
Remove User
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Users
# Users
##### [Get User](/docs/en/api/admin/users/retrieve)
GET/v1/organizations/users/{user_id}
##### [List Users](/docs/en/api/admin/users/list)
GET/v1/organizations/users
##### [Update User](/docs/en/api/admin/users/update)
POST/v1/organizations/users/{user_id}
##### [Remove User](/docs/en/api/admin/users/delete)
DELETE/v1/organizations/users/{user_id}
##### ModelsExpand Collapse
User object { id, added_at, email, 3 more }
id: string
ID of the User.
[](#user.id)
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
[](#user.added_at)
email: string
Email of the User.
[](#user.email)
name: string
Name of the User.
[](#user.name)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#user.role%5B0%5D)
"billing"
[](#user.role%5B1%5D)
"claude_code_user"
[](#user.role%5B2%5D)
"developer"
[](#user.role%5B3%5D)
"managed"
[](#user.role%5B4%5D)
"membership_admin"
[](#user.role%5B5%5D)
"owner"
[](#user.role%5B6%5D)
"primary_owner"
[](#user.role%5B7%5D)
"user"
[](#user.role%5B8%5D)
[](#user.role)
type: "user"
Object type.
For Users, this is always `"user"`.
[](#user.type)
[](#user)
UserDeleteResponse object { id, type }
id: string
ID of the User.
[](#user_delete_response.id)
type: "user_deleted"
Deleted object type.
For Users, this is always `"user_deleted"`.
[](#user_delete_response.type)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Users
GET/v1/organizations/users
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Query ParametersExpand Collapse
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.
[](#list.after_id)
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.
[](#list.before_id)
email: optional string
Filter by user email.
[](#list.email)
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
##### ReturnsExpand Collapse
data: array of [User](/docs/en/api/admin/users#user) { id, added_at, email, 3 more }
id: string
ID of the User.
[](#user.id)
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
[](#user.added_at)
email: string
Email of the User.
[](#user.email)
name: string
Name of the User.
[](#user.name)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#user.role%5B0%5D)
"billing"
[](#user.role%5B1%5D)
"claude_code_user"
[](#user.role%5B2%5D)
"developer"
[](#user.role%5B3%5D)
"managed"
[](#user.role%5B4%5D)
"membership_admin"
[](#user.role%5B5%5D)
"owner"
[](#user.role%5B6%5D)
"primary_owner"
[](#user.role%5B7%5D)
"user"
[](#user.role%5B8%5D)
[](#user.role)
type: "user"
Object type.
For Users, this is always `"user"`.
[](#user.type)
[](#list)
first_id: string
First ID in the `data` list. Can be used as the `before_id` for the previous page.
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
last_id: string
Last ID in the `data` list. Can be used as the `after_id` for the next page.
[](#list)
List Users
```python
curl https://api.anthropic.com/v1/organizations/users \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"name": "Jane Doe",
"role": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get User
GET/v1/organizations/users/{user_id}
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Path ParametersExpand Collapse
user_id: string
ID of the User.
[](#retrieve.user_id)
##### ReturnsExpand Collapse
User object { id, added_at, email, 3 more }
id: string
ID of the User.
[](#user.id)
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
[](#user.added_at)
email: string
Email of the User.
[](#user.email)
name: string
Name of the User.
[](#user.name)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#user.role%5B0%5D)
"billing"
[](#user.role%5B1%5D)
"claude_code_user"
[](#user.role%5B2%5D)
"developer"
[](#user.role%5B3%5D)
"managed"
[](#user.role%5B4%5D)
"membership_admin"
[](#user.role%5B5%5D)
"owner"
[](#user.role%5B6%5D)
"primary_owner"
[](#user.role%5B7%5D)
"user"
[](#user.role%5B8%5D)
[](#user.role)
type: "user"
Object type.
For Users, this is always `"user"`.
[](#user.type)
[](#user)
Get User
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"added_at": "2024-10-30T23:58:27.427722Z",
"email": "user@emaildomain.com",
"name": "Jane Doe",
"role": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update User
POST/v1/organizations/users/{user_id}
For Claude Enterprise organizations, this endpoint's availability is in beta.
##### Path ParametersExpand Collapse
user_id: string
ID of the User.
[](#update.user_id)
##### Body ParametersJSONExpand Collapse
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 (beta) accept `user` and `managed`.
One of the following:
"billing"
[](#update.role%5B0%5D)
"claude_code_user"
[](#update.role%5B1%5D)
"developer"
[](#update.role%5B2%5D)
"managed"
[](#update.role%5B3%5D)
"user"
[](#update.role%5B4%5D)
[](#update.role)
##### ReturnsExpand Collapse
User object { id, added_at, email, 3 more }
id: string
ID of the User.
[](#user.id)
added_at: string
RFC 3339 datetime string indicating when the User joined the Organization.
[](#user.added_at)
email: string
Email of the User.
[](#user.email)
name: string
Name of the User.
[](#user.name)
role: "admin" or "billing" or "claude_code_user" or 6 more
Organization role of the User.
One of the following:
"admin"
[](#user.role%5B0%5D)
"billing"
[](#user.role%5B1%5D)
"claude_code_user"
[](#user.role%5B2%5D)
"developer"
[](#user.role%5B3%5D)
"managed"
[](#user.role%5B4%5D)
"membership_admin"
[](#user.role%5B5%5D)
"owner"
[](#user.role%5B6%5D)
"primary_owner"
[](#user.role%5B7%5D)
"user"
[](#user.role%5B8%5D)
[](#user.role)
type: "user"
Object type.
For Users, this is always `"user"`.
[](#user.type)
[](#user)
Update User
```python
curl https://api.anthropic.com/v1/organizations/users/$USER_ID \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-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": "user",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Workspaces
# Workspaces
##### [Create Workspace](/docs/en/api/admin/workspaces/create)
POST/v1/organizations/workspaces
##### [Get Workspace](/docs/en/api/admin/workspaces/retrieve)
GET/v1/organizations/workspaces/{workspace_id}
##### [List Workspaces](/docs/en/api/admin/workspaces/list)
GET/v1/organizations/workspaces
##### [Update Workspace](/docs/en/api/admin/workspaces/update)
POST/v1/organizations/workspaces/{workspace_id}
##### [Archive Workspace](/docs/en/api/admin/workspaces/archive)
POST/v1/organizations/workspaces/{workspace_id}/archive
#### WorkspacesMembers
##### [Create Workspace Member](/docs/en/api/admin/workspaces/members/create)
POST/v1/organizations/workspaces/{workspace_id}/members
##### [Get Workspace Member](/docs/en/api/admin/workspaces/members/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [List Workspace Members](/docs/en/api/admin/workspaces/members/list)
GET/v1/organizations/workspaces/{workspace_id}/members
##### [Update Workspace Member](/docs/en/api/admin/workspaces/members/update)
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [Delete Workspace Member](/docs/en/api/admin/workspaces/members/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
#### WorkspacesRate Limits
##### [List Workspace Rate Limits](/docs/en/api/admin/workspaces/rate_limits/list)
GET/v1/organizations/workspaces/{workspace_id}/rate_limits
#### WorkspacesService Accounts
##### [Create Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/create)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Get Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [List Service Account Workspace Members](/docs/en/api/admin/workspaces/service_accounts/list)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Update Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/update)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [Delete Service Account Workspace Member](/docs/en/api/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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Archive
# Archive Workspace
POST/v1/organizations/workspaces/{workspace_id}/archive
Archive Workspace
##### Path ParametersExpand Collapse
workspace_id: string
[](#archive.workspace_id)
##### ReturnsExpand Collapse
Workspace object { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
[](#workspace.id)
archived_at: string
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
[](#workspace.archived_at)
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, including the value used during key validation.
[](#workspace.compartment_id)
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
[](#workspace.created_at)
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
[](#workspace.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#workspace.data_residency.allowed_inference_geos%5B1%5D)
[](#workspace.data_residency.allowed_inference_geos)
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
[](#workspace.data_residency.default_inference_geo)
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
[](#workspace.data_residency.workspace_geo)
[](#workspace.data_residency)
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
[](#workspace.display_color)
external_key_id: 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. 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.
[](#workspace.external_key_id)
name: string
Name of the Workspace.
[](#workspace.name)
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#workspace.tags)
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
[](#workspace.type)
[](#workspace)
Archive Workspace
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/archive \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Workspace
POST/v1/organizations/workspaces
Create Workspace
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
name: string
Name of the Workspace.
[](#create.name)
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.
One of the following:
array of string
[](#create.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#create.data_residency.allowed_inference_geos%5B1%5D)
[](#create.data_residency.allowed_inference_geos)
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"`.
[](#create.data_residency.default_inference_geo)
workspace_geo: optional string
Geographic region for workspace data storage. Immutable after creation. Defaults to 'us' if omitted.
[](#create.data_residency.workspace_geo)
[](#create.data_residency)
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. 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.
[](#create.external_key_id)
tags: optional map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#create.tags)
##### ReturnsExpand Collapse
Workspace object { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
[](#workspace.id)
archived_at: string
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
[](#workspace.archived_at)
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, including the value used during key validation.
[](#workspace.compartment_id)
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
[](#workspace.created_at)
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
[](#workspace.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#workspace.data_residency.allowed_inference_geos%5B1%5D)
[](#workspace.data_residency.allowed_inference_geos)
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
[](#workspace.data_residency.default_inference_geo)
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
[](#workspace.data_residency.workspace_geo)
[](#workspace.data_residency)
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
[](#workspace.display_color)
external_key_id: 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. 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.
[](#workspace.external_key_id)
name: string
Name of the Workspace.
[](#workspace.name)
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#workspace.tags)
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
[](#workspace.type)
[](#workspace)
Create Workspace
```python
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'Content-Type: application/json' \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
-d '{
"name": "x",
"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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Workspaces
GET/v1/organizations/workspaces
List Workspaces
##### Query ParametersExpand Collapse
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.
[](#list.after_id)
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.
[](#list.before_id)
include_archived: optional boolean
Whether to include Workspaces that have been archived in the response
[](#list.include_archived)
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
##### ReturnsExpand Collapse
data: array of [Workspace](/docs/en/api/$shared#workspace) { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
[](#workspace.id)
archived_at: string
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
[](#workspace.archived_at)
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, including the value used during key validation.
[](#workspace.compartment_id)
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
[](#workspace.created_at)
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
[](#workspace.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#workspace.data_residency.allowed_inference_geos%5B1%5D)
[](#workspace.data_residency.allowed_inference_geos)
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
[](#workspace.data_residency.default_inference_geo)
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
[](#workspace.data_residency.workspace_geo)
[](#workspace.data_residency)
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
[](#workspace.display_color)
external_key_id: 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. 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.
[](#workspace.external_key_id)
name: string
Name of the Workspace.
[](#workspace.name)
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#workspace.tags)
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
[](#workspace.type)
[](#list)
first_id: string
First ID in the `data` list. Can be used as the `before_id` for the previous page.
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
last_id: string
Last ID in the `data` list. Can be used as the `after_id` for the next page.
[](#list)
List Workspaces
```python
curl https://api.anthropic.com/v1/organizations/workspaces \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Members
# Members
##### [Create Workspace Member](/docs/en/api/admin/workspaces/members/create)
POST/v1/organizations/workspaces/{workspace_id}/members
##### [Get Workspace Member](/docs/en/api/admin/workspaces/members/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [List Workspace Members](/docs/en/api/admin/workspaces/members/list)
GET/v1/organizations/workspaces/{workspace_id}/members
##### [Update Workspace Member](/docs/en/api/admin/workspaces/members/update)
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### [Delete Workspace Member](/docs/en/api/admin/workspaces/members/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
##### ModelsExpand Collapse
WorkspaceMember object { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
[](#workspaceMember.type)
user_id: string
ID of the User.
[](#workspaceMember.user_id)
workspace_id: string
ID of the Workspace.
[](#workspaceMember.workspace_id)
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
[](#workspaceMember.workspace_role%5B0%5D)
"workspace_billing"
[](#workspaceMember.workspace_role%5B1%5D)
"workspace_developer"
[](#workspaceMember.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspaceMember.workspace_role%5B3%5D)
"workspace_user"
[](#workspaceMember.workspace_role%5B4%5D)
[](#workspaceMember.workspace_role)
[](#workspaceMember)
MemberDeleteResponse object { type, user_id, workspace_id }
type: "workspace_member_deleted"
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
[](#member_delete_response.type)
user_id: string
ID of the User.
[](#member_delete_response.user_id)
workspace_id: string
ID of the Workspace.
[](#member_delete_response.workspace_id)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/members
Create Workspace Member
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#create.workspace_id)
##### Body ParametersJSONExpand Collapse
user_id: string
ID of the User.
[](#create.user_id)
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"
[](#create.workspace_role%5B0%5D)
"workspace_developer"
[](#create.workspace_role%5B1%5D)
"workspace_restricted_developer"
[](#create.workspace_role%5B2%5D)
"workspace_user"
[](#create.workspace_role%5B3%5D)
[](#create.workspace_role)
##### ReturnsExpand Collapse
WorkspaceMember object { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
[](#workspaceMember.type)
user_id: string
ID of the User.
[](#workspaceMember.user_id)
workspace_id: string
ID of the Workspace.
[](#workspaceMember.workspace_id)
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
[](#workspaceMember.workspace_role%5B0%5D)
"workspace_billing"
[](#workspaceMember.workspace_role%5B1%5D)
"workspace_developer"
[](#workspaceMember.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspaceMember.workspace_role%5B3%5D)
"workspace_user"
[](#workspaceMember.workspace_role%5B4%5D)
[](#workspaceMember.workspace_role)
[](#workspaceMember)
Create Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Delete Workspace Member
DELETE/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Delete Workspace Member
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#delete.workspace_id)
user_id: string
ID of the User.
[](#delete.user_id)
##### ReturnsExpand Collapse
type: "workspace_member_deleted"
Deleted object type.
For Workspace Members, this is always `"workspace_member_deleted"`.
[](#member_delete_response.type)
user_id: string
ID of the User.
[](#member_delete_response.user_id)
workspace_id: string
ID of the Workspace.
[](#member_delete_response.workspace_id)
Delete Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Workspace Members
GET/v1/organizations/workspaces/{workspace_id}/members
List Workspace Members
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#list.workspace_id)
##### Query ParametersExpand Collapse
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.
[](#list.after_id)
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.
[](#list.before_id)
limit: optional number
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
maximum1000
minimum1
[](#list.limit)
##### ReturnsExpand Collapse
data: array of [WorkspaceMember](/docs/en/api/admin/workspaces/members#workspaceMember) { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
[](#workspaceMember.type)
user_id: string
ID of the User.
[](#workspaceMember.user_id)
workspace_id: string
ID of the Workspace.
[](#workspaceMember.workspace_id)
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
[](#workspaceMember.workspace_role%5B0%5D)
"workspace_billing"
[](#workspaceMember.workspace_role%5B1%5D)
"workspace_developer"
[](#workspaceMember.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspaceMember.workspace_role%5B3%5D)
"workspace_user"
[](#workspaceMember.workspace_role%5B4%5D)
[](#workspaceMember.workspace_role)
[](#list)
first_id: string
First ID in the `data` list. Can be used as the `before_id` for the previous page.
[](#list)
has_more: boolean
Indicates if there are more results in the requested page direction.
[](#list)
last_id: string
Last ID in the `data` list. Can be used as the `after_id` for the next page.
[](#list)
List Workspace Members
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Workspace Member
GET/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Get Workspace Member
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#retrieve.workspace_id)
user_id: string
ID of the User.
[](#retrieve.user_id)
##### ReturnsExpand Collapse
WorkspaceMember object { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
[](#workspaceMember.type)
user_id: string
ID of the User.
[](#workspaceMember.user_id)
workspace_id: string
ID of the Workspace.
[](#workspaceMember.workspace_id)
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
[](#workspaceMember.workspace_role%5B0%5D)
"workspace_billing"
[](#workspaceMember.workspace_role%5B1%5D)
"workspace_developer"
[](#workspaceMember.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspaceMember.workspace_role%5B3%5D)
"workspace_user"
[](#workspaceMember.workspace_role%5B4%5D)
[](#workspaceMember.workspace_role)
[](#workspaceMember)
Get Workspace Member
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/members/$USER_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/members/{user_id}
Update Workspace Member
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#update.workspace_id)
user_id: string
ID of the User.
[](#update.user_id)
##### Body ParametersJSONExpand Collapse
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"
[](#update.workspace_role%5B0%5D)
"workspace_billing"
[](#update.workspace_role%5B1%5D)
"workspace_developer"
[](#update.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#update.workspace_role%5B3%5D)
"workspace_user"
[](#update.workspace_role%5B4%5D)
[](#update.workspace_role)
##### ReturnsExpand Collapse
WorkspaceMember object { type, user_id, workspace_id, workspace_role }
type: "workspace_member"
Object type.
For Workspace Members, this is always `"workspace_member"`.
[](#workspaceMember.type)
user_id: string
ID of the User.
[](#workspaceMember.user_id)
workspace_id: string
ID of the Workspace.
[](#workspaceMember.workspace_id)
workspace_role: "workspace_admin" or "workspace_billing" or "workspace_developer" or 2 more
Role of the Workspace Member.
One of the following:
"workspace_admin"
[](#workspaceMember.workspace_role%5B0%5D)
"workspace_billing"
[](#workspaceMember.workspace_role%5B1%5D)
"workspace_developer"
[](#workspaceMember.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#workspaceMember.workspace_role%5B3%5D)
"workspace_user"
[](#workspaceMember.workspace_role%5B4%5D)
[](#workspaceMember.workspace_role)
[](#workspaceMember)
Update Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Rate limits
# Rate Limits
##### [List Workspace Rate Limits](/docs/en/api/admin/workspaces/rate_limits/list)
GET/v1/organizations/workspaces/{workspace_id}/rate_limits
##### ModelsExpand Collapse
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: "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"
[](#rate_limit_list_response.data.items.group_type%5B0%5D)
"files"
[](#rate_limit_list_response.data.items.group_type%5B1%5D)
"model_group"
[](#rate_limit_list_response.data.items.group_type%5B2%5D)
"skills"
[](#rate_limit_list_response.data.items.group_type%5B3%5D)
"token_count"
[](#rate_limit_list_response.data.items.group_type%5B4%5D)
"web_search"
[](#rate_limit_list_response.data.items.group_type%5B5%5D)
[](#rate_limit_list_response.data.items.group_type)
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.
[](#rate_limit_list_response.data.items.limits.items.org_limit)
type: string
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
[](#rate_limit_list_response.data.items.limits.items.type)
value: number
The workspace-level override value for this limiter type.
[](#rate_limit_list_response.data.items.limits.items.value)
[](#rate_limit_list_response.data.items.limits)
models: array of string
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
[](#rate_limit_list_response.data.items.models)
type: "workspace_rate_limit"
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
[](#rate_limit_list_response.data.items.type)
[](#rate_limit_list_response.data)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#rate_limit_list_response.next_page)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# 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.
##### Path ParametersExpand Collapse
workspace_id: string
The ID of the workspace.
[](#list.workspace_id)
##### Query ParametersExpand Collapse
group_type: optional "batch" or "files" or "model_group" or 3 more
Filter by group type.
One of the following:
"batch"
[](#list.group_type%5B0%5D)
"files"
[](#list.group_type%5B1%5D)
"model_group"
[](#list.group_type%5B2%5D)
"skills"
[](#list.group_type%5B3%5D)
"token_count"
[](#list.group_type%5B4%5D)
"web_search"
[](#list.group_type%5B5%5D)
[](#list.group_type)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### ReturnsExpand Collapse
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: "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"
[](#rate_limit_list_response.data.items.group_type%5B0%5D)
"files"
[](#rate_limit_list_response.data.items.group_type%5B1%5D)
"model_group"
[](#rate_limit_list_response.data.items.group_type%5B2%5D)
"skills"
[](#rate_limit_list_response.data.items.group_type%5B3%5D)
"token_count"
[](#rate_limit_list_response.data.items.group_type%5B4%5D)
"web_search"
[](#rate_limit_list_response.data.items.group_type%5B5%5D)
[](#rate_limit_list_response.data.items.group_type)
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.
[](#rate_limit_list_response.data.items.limits.items.org_limit)
type: string
The limiter type (for example, `requests_per_minute` or `input_tokens_per_minute`).
[](#rate_limit_list_response.data.items.limits.items.type)
value: number
The workspace-level override value for this limiter type.
[](#rate_limit_list_response.data.items.limits.items.value)
[](#rate_limit_list_response.data.items.limits)
models: array of string
Model names this entry's limits apply to, including aliases. `null` when `group_type` is not `"model_group"`.
[](#rate_limit_list_response.data.items.models)
type: "workspace_rate_limit"
Object type. Always `workspace_rate_limit` for workspace rate-limit entries.
[](#rate_limit_list_response.data.items.type)
[](#rate_limit_list_response.data)
next_page: string
Token to provide in as `page` in the subsequent request to retrieve the next page of data.
[](#rate_limit_list_response.next_page)
List Workspace Rate Limits
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/rate_limits \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"
```
Response 200
```python
{
"data": [
{
"group_type": "batch",
"limits": [
{
"org_limit": 0,
"type": "type",
"value": 0
}
],
"models": [
"string"
],
"type": "workspace_rate_limit"
}
],
"next_page": "next_page"
}
```
##### Returns Examples
Response 200
```python
{
"data": [
{
"group_type": "batch",
"limits": [
{
"org_limit": 0,
"type": "type",
"value": 0
}
],
"models": [
"string"
],
"type": "workspace_rate_limit"
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Workspace
GET/v1/organizations/workspaces/{workspace_id}
Get Workspace
##### Path ParametersExpand Collapse
workspace_id: string
ID of the Workspace.
[](#retrieve.workspace_id)
##### ReturnsExpand Collapse
Workspace object { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
[](#workspace.id)
archived_at: string
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
[](#workspace.archived_at)
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, including the value used during key validation.
[](#workspace.compartment_id)
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
[](#workspace.created_at)
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
[](#workspace.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#workspace.data_residency.allowed_inference_geos%5B1%5D)
[](#workspace.data_residency.allowed_inference_geos)
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
[](#workspace.data_residency.default_inference_geo)
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
[](#workspace.data_residency.workspace_geo)
[](#workspace.data_residency)
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
[](#workspace.display_color)
external_key_id: 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. 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.
[](#workspace.external_key_id)
name: string
Name of the Workspace.
[](#workspace.name)
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#workspace.tags)
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
[](#workspace.type)
[](#workspace)
Get Workspace
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Service accounts
# Service Accounts
##### [Create Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/create)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Get Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/retrieve)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [List Service Account Workspace Members](/docs/en/api/admin/workspaces/service_accounts/list)
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
##### [Update Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/update)
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### [Delete Service Account Workspace Member](/docs/en/api/admin/workspaces/service_accounts/delete)
DELETE/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
##### ModelsExpand Collapse
ServiceAccountCreateResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_create_response.created_by_actor_id)
implicit: boolean
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_create_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_create_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_create_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_create_response.workspace_id)
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"
[](#service_account_create_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_create_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_create_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_create_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_create_response.workspace_role%5B4%5D)
[](#service_account_create_response.workspace_role)
[](#service_account_create_response)
ServiceAccountRetrieveResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_retrieve_response.created_by_actor_id)
implicit: boolean
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_retrieve_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_retrieve_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_retrieve_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_retrieve_response.workspace_id)
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"
[](#service_account_retrieve_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_retrieve_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_retrieve_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_retrieve_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_retrieve_response.workspace_role%5B4%5D)
[](#service_account_retrieve_response.workspace_role)
[](#service_account_retrieve_response)
ServiceAccountListResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_list_response.created_by_actor_id)
implicit: boolean
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_list_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_list_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_list_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_list_response.workspace_id)
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"
[](#service_account_list_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_list_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_list_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_list_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_list_response.workspace_role%5B4%5D)
[](#service_account_list_response.workspace_role)
[](#service_account_list_response)
ServiceAccountUpdateResponse object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_update_response.created_by_actor_id)
implicit: boolean
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_update_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_update_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_update_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_update_response.workspace_id)
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"
[](#service_account_update_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_update_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_update_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_update_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_update_response.workspace_role%5B4%5D)
[](#service_account_update_response.workspace_role)
[](#service_account_update_response)
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.
[](#service_account_delete_response.service_account_id)
type: "service_account_workspace_member_deleted"
[](#service_account_delete_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
[](#service_account_delete_response.workspace_id)
[](#service_account_delete_response)
---
## 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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Create
# Create Service Account Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/service_accounts
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
workspace_id: string
ID of the workspace.
[](#create.workspace_id)
##### Header ParametersExpand Collapse
"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.
[](#create.anthropic-beta)
##### Body ParametersJSONExpand Collapse
service_account_id: string
Tagged service account ID to add.
[](#create.service_account_id)
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"
[](#create.workspace_role%5B0%5D)
"workspace_developer"
[](#create.workspace_role%5B1%5D)
"workspace_restricted_developer"
[](#create.workspace_role%5B2%5D)
"workspace_user"
[](#create.workspace_role%5B3%5D)
[](#create.workspace_role)
##### ReturnsExpand Collapse
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_create_response.created_by_actor_id)
implicit: boolean
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_create_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_create_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_create_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_create_response.workspace_id)
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"
[](#service_account_create_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_create_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_create_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_create_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_create_response.workspace_role%5B4%5D)
[](#service_account_create_response.workspace_role)
Create Service Account Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Delete
# Delete Service Account Workspace Member
DELETE/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
workspace_id: string
ID of the workspace.
[](#delete.workspace_id)
service_account_id: string
ID of the service account.
[](#delete.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#delete.anthropic-beta)
##### ReturnsExpand Collapse
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.
[](#service_account_delete_response.service_account_id)
type: "service_account_workspace_member_deleted"
[](#service_account_delete_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`) named in the delete request.
[](#service_account_delete_response.workspace_id)
Delete Service Account Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
List
# List Service Account Workspace Members
GET/v1/organizations/workspaces/{workspace_id}/service_accounts
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 ParametersExpand Collapse
workspace_id: string
ID of the workspace.
[](#list.workspace_id)
##### Query ParametersExpand Collapse
limit: optional number
Number of results per page.
[](#list.limit)
page: optional string
Opaque cursor from a previous response's `next_page`.
[](#list.page)
##### Header ParametersExpand Collapse
"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.
[](#list.anthropic-beta)
##### ReturnsExpand Collapse
data: array of object { created_by_actor_id, implicit, service_account_id, 3 more }
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_list_response.created_by_actor_id)
implicit: boolean
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_list_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_list_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_list_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_list_response.workspace_id)
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"
[](#service_account_list_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_list_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_list_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_list_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_list_response.workspace_role%5B4%5D)
[](#service_account_list_response.workspace_role)
[](#list)
next_page: string
Opaque cursor for the next page, or null if no more results.
[](#list)
List Service Account Workspace Members
```python
curl https://api.anthropic.com/v1/organizations/workspaces/$WORKSPACE_ID/service_accounts \
-H 'anthropic-version: 2023-06-01' \
-H "Authorization: Bearer $ANTHROPIC_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Retrieve
# Get Service Account Workspace Member
GET/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
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 ParametersExpand Collapse
workspace_id: string
ID of the workspace.
[](#retrieve.workspace_id)
service_account_id: string
ID of the service account.
[](#retrieve.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#retrieve.anthropic-beta)
##### ReturnsExpand Collapse
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_retrieve_response.created_by_actor_id)
implicit: boolean
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_retrieve_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_retrieve_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_retrieve_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_retrieve_response.workspace_id)
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"
[](#service_account_retrieve_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_retrieve_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_retrieve_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_retrieve_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_retrieve_response.workspace_role%5B4%5D)
[](#service_account_retrieve_response.workspace_role)
Get Service Account Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Service Account Workspace Member
POST/v1/organizations/workspaces/{workspace_id}/service_accounts/{service_account_id}
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. Requires an OAuth bearer or Console session; Admin API keys are not accepted.
##### Path ParametersExpand Collapse
workspace_id: string
ID of the workspace.
[](#update.workspace_id)
service_account_id: string
ID of the service account.
[](#update.service_account_id)
##### Header ParametersExpand Collapse
"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.
[](#update.anthropic-beta)
##### Body ParametersJSONExpand Collapse
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"
[](#update.workspace_role%5B0%5D)
"workspace_developer"
[](#update.workspace_role%5B1%5D)
"workspace_restricted_developer"
[](#update.workspace_role%5B2%5D)
"workspace_user"
[](#update.workspace_role%5B3%5D)
[](#update.workspace_role)
##### ReturnsExpand Collapse
created_by_actor_id: string
Tagged ID (`user_...`/`svac_...`) of the actor who created this membership.
[](#service_account_update_response.created_by_actor_id)
implicit: boolean
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_update_response.implicit)
service_account_id: string
Tagged service account ID (`svac_...`).
[](#service_account_update_response.service_account_id)
type: "service_account_workspace_member"
[](#service_account_update_response.type)
workspace_id: string
Tagged workspace ID (`wrkspc_...`).
[](#service_account_update_response.workspace_id)
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"
[](#service_account_update_response.workspace_role%5B0%5D)
"workspace_billing"
[](#service_account_update_response.workspace_role%5B1%5D)
"workspace_developer"
[](#service_account_update_response.workspace_role%5B2%5D)
"workspace_restricted_developer"
[](#service_account_update_response.workspace_role%5B3%5D)
"workspace_user"
[](#service_account_update_response.workspace_role%5B4%5D)
[](#service_account_update_response.workspace_role)
Update Service Account Workspace Member
```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_OAUTH_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/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
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
Models
List Models
Get a Model
Dreams
Create a Dream
List Dreams
Get a Dream
Cancel a Dream
Archive a Dream
Files
Upload File
List Files
Download File
Get File Metadata
Delete File
Skills
Create Skill
List Skills
Get Skill
Delete Skill
Versions
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
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
Claude Code
[Trigger a routine](/docs/en/api/claude-code/routines-fire)
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)
[](/login)
API reference
Update
# Update Workspace
POST/v1/organizations/workspaces/{workspace_id}
Update Workspace
##### Path ParametersExpand Collapse
workspace_id: string
[](#update.workspace_id)
##### Body ParametersJSONExpand Collapse
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.
One of the following:
array of string
[](#update.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#update.data_residency.allowed_inference_geos%5B1%5D)
[](#update.data_residency.allowed_inference_geos)
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"`.
[](#update.data_residency.default_inference_geo)
[](#update.data_residency)
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. 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.
[](#update.external_key_id)
name: optional string
Name of the Workspace.
[](#update.name)
tags: optional map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#update.tags)
##### ReturnsExpand Collapse
Workspace object { id, archived_at, compartment_id, 7 more }
id: string
ID of the Workspace.
[](#workspace.id)
archived_at: string
RFC 3339 datetime string indicating when the Workspace was archived, or `null` if the Workspace is not archived.
[](#workspace.archived_at)
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, including the value used during key validation.
[](#workspace.compartment_id)
created_at: string
RFC 3339 datetime string indicating when the Workspace was created.
[](#workspace.created_at)
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
[](#workspace.data_residency.allowed_inference_geos%5B0%5D)
"unrestricted"
[](#workspace.data_residency.allowed_inference_geos%5B1%5D)
[](#workspace.data_residency.allowed_inference_geos)
default_inference_geo: string
Default inference geo applied when requests omit the parameter.
[](#workspace.data_residency.default_inference_geo)
workspace_geo: string
Geographic region for workspace data storage. Immutable after creation.
[](#workspace.data_residency.workspace_geo)
[](#workspace.data_residency)
display_color: string
Hex color code representing the Workspace in the Anthropic Console.
[](#workspace.display_color)
external_key_id: 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. 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.
[](#workspace.external_key_id)
name: string
Name of the Workspace.
[](#workspace.name)
tags: map\[string\]
User-defined tags as string key-value pairs. Keys may not begin with `anthropic`.
[](#workspace.tags)
type: "workspace"
Object type.
For Workspaces, this is always `"workspace"`.
[](#workspace.type)
[](#workspace)
Update Workspace
```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_OAUTH_TOKEN" \
-d '{
"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",
---
## 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
Best practices
Messages/Skills
# 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):
```` 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:
``` inline-block
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.
``` inline-block
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:**
``` inline-block
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
Create your first Skill
Use Skills in Claude Code
Create and manage Skills in Claude Code
Use Skills with the API
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
Skills for enterprise
Messages/Skills
# 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 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.
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 8 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. 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
Architecture and platform details
Best practices
Authoring guidance for Skill creators
Using Skills with the API
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
Overview
Messages/Skills
# 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.
For 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:
``` inline-block
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.
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, and one beta header:
- `skills-2025-10-02` - Enables Skills functionality
Add a second header, `files-api-2025-04-14`, when you use the [Files API](/docs/en/build-with-claude/files) to upload input files to the container or download files a Skill produces.
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).
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).
Limitations and constraints
Claude Platform on AWS and Microsoft Foundry follow the same limitations as the Claude API in the following subsections.
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
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
Using Agent Skills with the API
Learn how to use Agent Skills to extend Claude's capabilities through the API.
Use Skills in Claude Code
Create and manage custom Skills in Claude Code.
Skill authoring 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
Quickstart
Messages/Skills
# 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 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
ant beta:skills list --source anthropic
```
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.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
betas=["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_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#model-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)
- **Beta header:** `skills-2025-10-02`
The examples on this page use the `code_execution_20260521` tool version, which is generally available and needs only the `skills-2025-10-02` beta header. 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, keep its tool `type` and any beta header consistent with the code execution tool page, and always include `skills-2025-10-02`.
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.beta.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.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
betas=["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_20260521", "name": "code_execution"}],
)
```
Create a Word document
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
betas=["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_20260521", "name": "code_execution"}],
)
```
Generate a PDF
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
```python
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
betas=["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_20260521", "name": "code_execution"}],
)
```
Next steps
Skill authoring best practices
Learn how to write effective Skills that Claude can discover and use successfully.
Using Agent Skills with the API
Learn how to use Agent Skills to extend Claude's capabilities through the API.
Create custom Skills
Upload your own Skills for specialized tasks.
Use Skills in Claude Code
Learn about Skills in Claude Code.
Agent Skills Cookbook
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
MCP connector
Messages/MCP
# MCP connector
Connect to remote MCP servers directly from the Messages API without an MCP client, and allowlist, denylist, or configure individual tools.
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.
**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 [Deprecated version: mcp-client-2025-04-04](#deprecated-version-mcp-client-2025-04-04).
For how zero data retention (ZDR) applies to this feature, see [API and data retention](/docs/en/manage-claude/api-and-data-retention).
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.
- The MCP connector is available on 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, the MCP connector requires a [Hosted on Anthropic deployment](/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure). It is not currently available on Amazon Bedrock or Google Cloud.
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",
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 [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). |
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. |
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). 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:
```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"
}
]
}
```
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",
"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 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 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
Python
TypeScript
TypeScript
C#
C#
Go
Go
Java
Java
PHP
PHP
Ruby
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",
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",
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",
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.beta.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
Error handling
The conversion functions throw `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API (in Go, the helpers return an `UnsupportedValueError`; in Java and C#, they throw `AnthropicInvalidDataException`). 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",
"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",
"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 |
---
## 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Architecture and components
Messages/MCP tunnels
# Architecture and components
Canonical names for the parts of an MCP tunnel deployment, the two credential-provisioning modes, and the connection model.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Manage in the Console
Messages/MCP tunnels
# Manage tunnels in the Console
Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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
Run the tunnel stack on a single host. Both programmatic-access and manual flows.
Deploy with 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
Install on a Kubernetes cluster using the Anthropic Helm chart.
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Deploy with Docker Compose
Messages/MCP tunnels
# Deploy MCP tunnels with Docker Compose
Install the MCP tunnel stack on a VM using Docker Compose.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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
With programmatic access
Without 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
Attach an upstream MCP server to a Managed Agent or the Messages API.
Security
Hardening guidance, credential rotation, and breach response.
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Deploy with Helm
Messages/MCP tunnels
# Deploy MCP tunnels with Helm
Install the tunnel stack on a Kubernetes cluster using the Anthropic Helm chart.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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
With programmatic access
Without 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
Attach an upstream MCP server to a Managed Agent or the Messages API.
Security
Hardening guidance, credential rotation, and breach response.
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Overview
Messages/MCP tunnels
# MCP tunnels
Securely connect Claude to MCP servers running in your private network without opening inbound ports or exposing services to the public internet.
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/claude-managed-agents) 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
The shortest path to a working tunnel: Docker Compose with a sample MCP server.
Deploy with Helm
Install on a Kubernetes cluster using the Anthropic Helm chart.
Deploy with Docker 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). Use an API key for the workspace the tunnel was created in (Console **Settings \> API keys**).
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",
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
Hardening guidance, credential rotation, and breach response.
Troubleshooting
Diagnose connectivity, TLS, and routing issues.
Reference
Proxy config fields, the Tunnels API, certificate requirements, and the setup component.
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Quickstart
Messages/MCP tunnels
# MCP tunnels quickstart
Connect Claude to a private MCP server using a local Docker Compose deployment.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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
macOS / Linux
Windows (PowerShell)
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
macOS / Linux
Windows (PowerShell)
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
macOS / Linux
Windows (PowerShell)
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
macOS / Linux
Windows (PowerShell)
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
macOS / Linux
Windows (PowerShell)
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
Hardened single-host deployment, with or without programmatic access.
Deploy with 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Reference
Messages/MCP tunnels
# MCP tunnels reference
Proxy configuration fields, the Tunnels REST API, certificate requirements, and the setup component.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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/admin/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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Security
Messages/MCP tunnels
# MCP tunnels security
Hardening guidance, credential rotation, breach response, and teardown for MCP tunnel deployments.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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
Helm
Docker Compose
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
Helm
Docker Compose
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
Helm
Docker Compose
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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
[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)
[](/login)
Messages
Troubleshooting
Messages/MCP tunnels
# Troubleshoot MCP tunnels
Diagnose connectivity, TLS, IP validation, and OAuth routing issues in a tunnel stack.
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) 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/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
First steps
[Intro to Claude](/docs/en/intro)[Get your API key](/docs/en/get-api-key)[Quickstart](/docs/en/get-started)
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
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)[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)[Compaction](/docs/en/build-with-claude/compaction)[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 (beta)](/docs/en/build-with-claude/cache-diagnostics)[Token counting](/docs/en/build-with-claude/token-counting)
Working with files
[Files API](/docs/en/build-with-claude/files)[PDF support](/docs/en/build-with-claude/pdf-support)
Images and 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
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)
[](/login)
Messages
Remote MCP servers
Messages/MCP
# Remote MCP servers
Connect Claude to third-party remote MCP servers through the MCP connector API. Browse example servers and review the steps to connect.
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](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
`https://mcp.tickettailor.ai/mcp`
[Linear](https://linear.app/docs/mcp)
Manage issues, projects & team workflows in Linear
URL
`https://mcp.linear.app/mcp`
[Hugging Face](https://huggingface.co/settings/mcp)
Access the Hugging Face Hub and thousands of Gradio Apps
URL
`https://huggingface.co/mcp?login&gradio=none`
[Blockscout](https://github.com/blockscout/mcp-server)
Access and analyze blockchain data
URL
`https://mcp.blockscout.com/mcp`
[Close](https://help.close.com/v1/docs/en/mcp-server)
Connect Claude to Close CRM to securely access and act on your sales data
URL
`https://mcp.close.com/mcp`
[Cloudflare Developer Platform](https://www.support.cloudflare.com/)
Build applications with compute, storage, and AI
URL
`https://bindings.mcp.cloudflare.com/mcp`
[Egnyte](https://developers.egnyte.com/docs/Remote_MCP_Server)
Securely access and analyze Egnyte content
URL
`https://mcp-server.egnyte.com/mcp`
[Figma](https://help.figma.com/hc/en-us/articles/32132100833559)
Generate diagrams and better code from Figma context
URL
`https://mcp.figma.com/mcp`
[Guru](https://help.getguru.com/docs/connecting-gurus-mcp-server)
Search and interact with your company knowledge
URL
`https://mcp.api.getguru.com/mcp`
[Jotform](https://www.jotform.com/developers/mcp/)
Create forms & analyze submissions inside Claude
URL
`https://mcp.jotform.com/mcp-app`
[monday.com](https://developer.monday.com/apps/docs/mondaycom-mcp-integration)
Manage projects, boards, and workflows in monday.com
URL
`https://mcp.monday.com/mcp`
[Notion](https://developers.notion.com/docs/mcp)
Connect your Notion workspace to search, update, and power workflows across tools
URL
`https://mcp.notion.com/mcp`
[PayPal](https://mcp.paypal.com/)
Access PayPal payments platform
URL
`https://mcp.paypal.com/mcp`
[Stripe](https://docs.stripe.com/mcp)
Payment processing and financial infrastructure tools
URL
`https://mcp.stripe.com`
[Supabase](https://supabase.com/docs/guides/getting-started/mcp)
Manage databases, authentication, and storage
URL
`https://mcp.supabase.com/mcp`
[Vercel](https://vercel.com/docs/mcp/vercel-mcp)
Analyze, debug, and manage projects and deployments
URL
`https://mcp.vercel.com/`
[Wix](https://dev.wix.com/docs/sdk/articles/use-the-wix-mcp/about-the-wix-mcp)
Manage and build sites and apps on Wix
URL
`https://mcp.wix.com/mcp`
[Coupler.io](https://help.coupler.io/article/592-coupler-local-mcp-server)
Access business data from hundreds of sources
URL
`https://mcp.coupler.io/mcp/`
[Dice](https://www.dice.com/about/mcp)
Find active tech jobs on Dice
URL
`https://mcp.dice.com/mcp`
[Miro](https://developers.miro.com/docs/miro-mcp)
Access and create new content on Miro boards
URL
`https://mcp.miro.com/`
[Port IO](https://docs.port.io/ai-interfaces/port-mcp-server/overview-and-installation)
Search your context lake and safely run actions
Requires user-specific URL. [Get your URL here](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)](https://docs.columntax.com/page/aiwyn-tax-mcp-server)
Estimate your federal & state taxes with Aiwyn's tax engine
URL
`https://mcp.columnapi.com/mcp`
[Circleback](https://circleback.ai/docs/mcp)
Search and access context from meetings
URL
`https://app.circleback.ai/api/mcp`
[Clarify](https://docs.clarify.ai/en/articles/13367278-clarify-mcp)
Query your CRM. Create records. Ask anything.
URL
`https://api.clarify.ai/mcp`
[Clarity AI](https://clarity-sfdr20-mcp.pro.clarity.ai/)
Simulate fund classifications under proposed SFDR 2.0
URL
`https://clarity-sfdr20-mcp.pro.clarity.ai/mcp`
[Day AI](https://day.ai/mcp)
Know everything about your prospects & customers with CRMx
URL
`https://day.ai/api/mcp`
[ICD-10 Codes](https://claude.com/resources/tutorials/using-the-icd-10-connector-in-claude)
Access ICD-10-CM and ICD-10-PCS code sets
URL
`https://hcls.mcp.claude.com/icd10_codes/mcp`
[DevRev](https://support.devrev.ai/en-US/devrev/article/ART-21859-remote-mcp-server)
Search and update your company's knowledge graph
URL
`https://api.devrev.ai/mcp/v1`
[DirectBooker](https://www.directbooker.ai/products/mcp-server-documentation)
Compare hotels, then book direct
URL
`https://www.directbooker.ai/claude`
[Exa](https://docs.exa.ai/reference/exa-mcp)
Web Search + Code Docs Search
URL
`https://mcp.exa.ai/mcp`
[Fathom](https://help.fathom.video/en/articles/11497793)
Your meetings, now part of every Claude conversation
URL
`https://api.fathom.ai/mcp`
[Fireflies](https://guide.fireflies.ai/articles/8272956938-learn-about-the-fireflies-mcp-server-model-context-protocol)
Analyze and generate insights from meeting transcripts
URL
`https://api.fireflies.ai/mcp`
[Fiscal.ai](https://docs.fiscal.ai/docs/guides/mcp-integration)
Clean Public Equity Fundamental Data
URL
`https://api.fiscal.ai/mcp/sse`
[Granola](https://help.granola.ai/article/granola-mcp#set-up-guide)
The AI notepad for meetings
URL
`https://mcp.granola.ai/mcp`
[Harmonic](https://support.harmonic.ai/en/articles/12785899-harmonic-mcp-server-getting-started-guide)
Discover, research, and enrich companies and people
URL
`https://mcp.api.harmonic.ai`
[Klarity](https://github.com/Klarity-AI/klarity-mcp/blob/main/skills/klarity-process-context-graph/SKILL.md)
Explore your org's processes
URL
`https://architect-v2-api.klarity.ai/mcp`
[Krisp](https://help.krisp.ai/hc/en-us/articles/25416265429660-Krisp-MCP-Supported-tools)
Add your meetings context via transcripts and notes
URL
`https://mcp.krisp.ai/mcp`
[Lawve AI](https://lawve.ai/en/learn/mcp-setup)
Discover expert-written skills for legal work
URL
`https://mcp.lawve.ai/mcp`
[Lorikeet](https://docs.lorikeetcx.ai/mcp/mcp-server)
A universal concierge for complex businesses
URL
`https://mcp.lorikeetcx.ai`
[LunarCrush](https://lunarcrush.com/developers/api/ai)
Add real-time social media data to your searches
URL
`https://lunarcrush.ai/mcp`
[Mem](https://docs.mem.ai/mcp/overview)
The AI notebook for everything on your mind
URL
`https://mcp.mem.ai/mcp`
[Metaview](https://support.metaview.ai/integrations/mcp-integration/mcp-overview.mdx)
The AI platform for recruiting.
URL
`https://mcp.metaview.ai/mcp`
[Otter.ai](https://help.otter.ai/hc/en-us/articles/35287607569687-Otter-MCP-Server)
Unlock your meeting intelligence
URL
`https://mcp.otter.ai/mcp`
[Peec AI](https://docs.peec.ai/mcp/introduction)
Analyze your brand's visibility across LLMs
URL
`https://api.peec.ai/mcp`
[Read AI](https://support.read.ai/hc/en-us/articles/49381158409491-MCP-Server)
Bring your meetings into Claude
URL
`https://api.read.ai/mcp`
[Scholar Gateway](https://docs.scholargateway.ai)
Enhance responses with scholarly research and citations
URL
`https://connector.scholargateway.ai/mcp`
[Scite](https://scite.ai/mcp)
Evidence-based answers grounded in research
URL
`https://api.scite.ai/mcp`
[Sprouts Data Intelligence](https://support.sprouts.ai/en/articles/13384582-sprouts-mcp-server-documentation#h_541c149a52)
From query to qualified lead in seconds.
URL
`https://sprouts-mcp-server.kartikay-dhar.workers.dev`
[Sybill](https://api.sybill.ai/docs/mcp.html)
Ask AI about your sales calls, deals & pipeline
URL
`https://mcp.sybill.ai/mcp`
[Tray.ai](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
Automate 700+ apps & workflows with governance
Requires user-specific URL. [Get your URL here](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
[Vibe Prospecting](https://developers.explorium.ai/mcp-docs/agentsource-mcp)
Find company & contact data
URL
`https://vibeprospecting.explorium.ai/mcp`
[Windsor.ai](https://windsor.ai/introducing-windsor-mcp/#method-1-using-claude-desktop-3)
Connect Meta Ads, Google Ads, TikTok Ads, LinkedIn Ads + 320 more
URL
`https://mcp.windsor.ai`
[Era Context](https://era.app/help/mcp-server-era-context/)
Manage your personal finances using Claude
URL
`https://context.era.app`
[Fellow.ai](https://help.fellow.ai/en/articles/12622641-fellow-s-mcp-server)
Chat with your meetings to uncover actionable insights
URL
`https://fellow.app/mcp`
[Gamma](https://gamma.app/docs/Gamma-MCP-Server-Documentation-m6p43kobgzy15zj?mode=doc)
Create presentations, docs, socials, and sites with AI
URL
`https://mcp.gamma.app/mcp`
[Lucid](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
`https://mcp.lucid.app/mcp`
[Natoma](https://docs.natoma.ai)
Access all your internal tools, enterprise apps & data.
Requires user-specific URL. [Get your URL here](https://natoma.app/?utm=claude)
[NetDocuments](https://support.netdocuments.com/)
Securely access your documents in NetDocuments
[Netlify](https://docs.netlify.com/build/build-with-ai/netlify-mcp-server/)
Create, deploy, manage, and secure websites on Netlify.
URL
`https://netlify-mcp.netlify.app/mcp`
[ThoughtSpot Spotter](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
`https://agent.thoughtspot.app/mcp?api-version=latest`
[AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/APIReference/marketplace-mcp-server.html)
Discover, evaluate, and buy solutions for the cloud
URL
`https://marketplace-mcp.us-east-1.api.aws/mcp`
[Synthesize Bio](https://app.synthesize.bio/mcp/docs)
Generate gene expression from a virtual human
URL
`https://app.synthesize.bio/api/mcp`
[Kindora Funder Discovery](https://kindora.co/mcp)
Find funders who support causes like yours
URL
`https://kindora-mcp.azurewebsites.net/mcp/`
[Omni Analytics](https://docs.omni.co/ai/mcp)
Query your data using natural language through Omni's semantic model
URL
`https://callbacks.omniapp.co/callback/mcp`
[Send](https://www.send.co/mcp/docs)
Create shareable documents, one-pagers, and decks
URL
`https://www.send.co/mcp`
[Shapes](https://mcp.shapes.co)
Analyse your live people data, right in Claude
URL
`https://mcp.shapes.co/mcp`
[Lloyd by The L Suite](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 user-specific URL. [Get your URL here](https://docs.google.com/forms/d/e/1FAIpQLSeK2KFt1G1XbqgQdp2J-cvnLDtiUDigSsTjFH-Hk_B-Va0pRw/viewform?usp=publish-editor)
[TopCounsel by The L Suite](https://docs.google.com/document/d/1jcekau3Njlc5XfSspSdSGu7qSgKvM00M6DrYm91ZTzA/edit?tab=t.0#heading=h.hgwkvyizzdb3)
Outside Counsel recommendations from Inhouse Counsel
URL
`https://api.techgc.co/api/mcp/topcounsel`
[ActiveCampaign](https://developers.activecampaign.com/page/mcp)
Autonomous marketing to transform how you work
Requires user-specific URL. [Get your URL here](https://developers.activecampaign.com/page/mcp)
[Adobe Experience Manager](https://www.adobe.com/go/aem_claude_mcp_docs)
Manage your Adobe Experience Manager content
URL
`https://mcp.adobeaemcloud.com/adobe/mcp/aem`
[Ahrefs](https://docs.ahrefs.com/docs/mcp/reference/introduction)
SEO & AI search analytics
URL
`https://api.ahrefs.com/mcp/mcp`
[AirOps](https://docs.airops.com/mcp)
Craft content that wins AI search
URL
`https://app.airops.com/mcp`
[Airtable](https://support.airtable.com/docs/using-the-airtable-mcp-server)
Bring your structured data to Claude
URL
`https://mcp.airtable.com/mcp`
[Airwallex Developer](https://www.airwallex.com/docs/developer-tools/ai/developer-mcp)
Integrate with the Airwallex Platform using Claude
URL
`https://mcp-demo.airwallex.com/developer`
[AllTrails](https://support.alltrails.com/hc/en-us/articles/47343827423764-AllTrails-integrations-with-AI-services)
Find your next hike
URL
`https://www.alltrails.com/mcp`
[Attio](https://docs.attio.com/mcp/overview)
Search, manage, and update your Attio CRM from Claude
URL
`https://mcp.attio.com/mcp`
[Audible](https://help.audible.com/s/article/connect-audible-to-claude?language=en_US)
Ask for audiobook recommendations
URL
`https://mcp.audible.com/mcp`
[Autodesk Product Help](https://help.autodesk.com/view/ADSKMCP/ENU/?guid=ADSKMCP_KnowledgeMcp_autodesk_product_help_mcp_server_html)
Securely access Autodesk's help documentation
URL
`https://developer.api.autodesk.com/knowledge/public/v1/mcp`
[Base44](https://docs.base44.com/developers/backend/overview/mcp-server)
Build and manage Base44 apps
URL
`https://app.base44.com/mcp`
[Benchling](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
Connect to R&D data, source experiments, and notebooks
Requires user-specific URL. [Get your URL here](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
[BioRender](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
`https://mcp.services.biorender.com/mcp`
[Bitly](https://dev.bitly.com/bitly-mcp/)
Shorten links, generate QR Codes, and track performance
URL
`https://api-ssl.bitly.com/v4/mcp`
[MT Newswires](https://console.blueskyapi.com/docs/EDGE/news/MT_NEWSWIRES_Global#mcp)
Trusted real-time global financial news provider
URL
`https://vast-mcp.blueskyapi.com/mcp`
[Booking.com](https://developers.booking.com/mcp/booking-connector/about)
Find hotels, homes and more
URL
`https://demandapi-mcp.booking.com/v1/mcp/8132308`
[Box](https://developer.box.com/guides/box-mcp)
Search, edit and get insights on your Box content
URL
`https://mcp.box.com`
[Brex](https://www.brex.com/support/using-brex-in-ai-apps)
Intelligent finance automation
URL
`https://api.brex.com/mcp`
[Orion by Gravity](http://docs.runorion.com/)
Get insights from your autonomous AI analyst
URL
`https://g.runorion.com/mcp`
[Calendly](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
`https://mcp.calendly.com`
[Canva](https://www.canva.dev/docs/connect/canva-mcp-server-setup/)
Search, create, autofill, and export Canva designs
URL
`https://mcp.canva.com/mcp`
[Carta](https://docs.carta.com/api-platform/docs/claude-plugins-setup)
The connected ERP for private capital
URL
`https://mcp.app.carta.com/mcp`
[CB Insights](https://mcp.cbinsights.com)
Predictive intelligence on private companies
URL
`https://mcp.cbinsights.com`
[CData Connect AI](https://cloud.cdata.com/docs/Claude-Client.html)
Managed MCP platform for 350 sources
URL
`https://mcp.cloud.cdata.com/mcp`
[Microsoft 365](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
`https://microsoft365.mcp.claude.com/mcp`
[PubMed](https://support.claude.com/en/)
Search biomedical literature from PubMed
URL
`https://pubmed.mcp.claude.com/mcp`
[Clay](https://www.notion.so/clayrun/Clay-Claude-MCP-Server-Documentation-2ef7e66eb01480c9820de48041591aeb?showMoveTo=true&saveParent=true)
Find prospects. Research accounts. Personalize outreach
URL
`https://api.clay.com/v3/mcp`
[Clerk](https://clerk.com/docs/guides/ai/mcp/clerk-mcp-server)
Add authentication, organizations, and billing
URL
`https://mcp.clerk.com/mcp`
[ClickUp](https://help.clickup.com/hc/en-us/articles/33335772678423-What-is-ClickUp-MCP)
Project management & collaboration for teams & agents
URL
`https://mcp.clickup.com/mcp`
[iManage Work](https://docs.imanage.com/cloud/mcpconnector-user-help/en-US/iManage_MCP_Connector_Help.html)
Governed knowledge. AI ready.
URL
`https://cloudimanage.com/mcp/work`
[Cloudinary](https://cloudinary.com/documentation/cloudinary_llm_mcp#available_mcp_servers)
Manage, transform and deliver your images & videos
URL
`https://asset-management.mcp.cloudinary.com/sse`
[CoinDesk](https://mcp.coindesk.com/)
Access Live & Historical Crypto Data, Indices
URL
`https://mcp.coindesk.com/mcp`
[Consensus](https://docs.consensus.app/docs/mcp)
Explore scientific research
URL
`https://mcp.consensus.app/mcp`
[Aurora](https://mcp-docs.ai.consilio.com)
Search your Consilio matters, docs, and more.
URL
`https://mcp.ai.consilio.com`
[Contentsquare](https://support.contentsquare.com/hc/en-us/articles/41563169756945-Model-Context-Protocol-MCP)
Experience analytics platform for digital businesses
URL
`https://api.contentsquare.com/mcp`
[Context7](https://context7.com/docs/overview)
Up-to-date docs for LLMs and AI code editors
URL
`https://mcp.context7.com/mcp`
[CourtListener](https://github.com/freelawproject/courtlistener-api-client/blob/main/MCP_README.md)
Legal research across millions of court records
URL
`https://mcp.courtlistener.com/`
[Courtroom5](https://courtroom5.com/claude)
Civil legal guidance for self-represented litigants
URL
`https://mcp.courtroom5.com/v1`
[Intuit Credit Karma](https://support.creditkarma.com/s/article/Intuit-Credit-Karma-on-Claude-and-ChatGPT)
Credit score factors & insights
URL
`https://anthropic.mcp.creditkarma.com/mcp`
[Crossbeam](https://help.crossbeam.com/en/articles/12601327-crossbeam-mcp-server-beta)
Explore partner data and ecosystem insights in Claude
URL
`https://mcp.crossbeam.com`
[Crypto.com](https://mcp.crypto.com/docs)
Real time prices, orders, charts, and more for crypto
URL
`https://mcp.crypto.com/market-data/mcp`
[Daloopa](https://docs.daloopa.com/docs/daloopa-mcp#/)
Financial fundamental data and KPIs with hyperlinks
URL
`https://mcp.daloopa.com/server/mcp`
[Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
Managed MCP servers with Unity Catalog and Mosaic AI
Requires user-specific URL. [Get your URL here](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
[Datadog](https://docs.datadoghq.com/bits_ai/mcp_server/)
Debug and resolve issues using Datadog telemetry
[Datasite](https://app.global.datasite.com/dev-portal/guides/mcp-server)
Manage your M&A data room from Claude
URL
`https://mcp.global.datasite.com/mcp`
[Definely](https://help.definely.com/en/articles/634922-definely-connector-for-claude-user-guide)
Structured contract review tools for legal teams
URL
`https://mcp.app.definely.com`
[Descript](https://help.descript.com/hc/en-us/articles/45008080343053-Connect-Descript-to-Claude)
Import, edit, or create video with prompts
URL
`https://api.descript.com/v2/mcp/claude`
[Descrybe Legal Engine](https://app.descrybe.com/connect/docs)
Ground your work in clean, structured U.S. primary law
URL
`https://mcp.descrybe.com/mcp`
[Digits](https://help.digits.com/business-connections/digits-mcp-claude)
Track and analyze your finances with Digits
URL
`https://api.digits.com/mcp`
[D&B Risk Analytics](https://view.highspot.com/viewer/2b3c0624606b4d64eb092106b47ad14c)
Execute risk workflows powered by the D&B Commercial Graph™
URL
`https://agents.riskanalytics.dnb.com/mcp`
[DocuSeal](https://www.docuseal.com/guides/integrate-with-ai-agents-using-mcp)
Sign, send & manage documents with DocuSeal
URL
`https://docuseal.com/mcp`
[Dovetail](https://developers.dovetail.com/docs/mcp)
Turn scattered feedback into decisions grounded in customer evidence
URL
`https://dovetail.com/api/mcp`
[Dremio Cloud](https://docs.dremio.com/cloud/sonar/mcp-server/)
Analyze and get insights from your lakehouse data
Requires user-specific URL. [Get your URL here](https://docs.dremio.com/cloud/sonar/mcp-server/)
[Enterpret](https://helpcenter.enterpret.com/en/articles/12665166-wisdom-mcp-server)
Get answers from unified feedback of your customers.
URL
`https://wisdom-api.enterpret.com/server/mcp`
[Euler](https://mcp.eulerapp.com/public/docs)
Chat and manage your entire partner program.
URL
`https://mcp.eulerapp.com/mcp`
[Everlaw](https://support.everlaw.com/hc/en-us/articles/50274473477915)
Search and explore your Everlaw database in Claude.
URL
`https://api.everlaw.com/v1/mcp`
[Expedia](https://www.expedia.com/playground/mcp/doc/)
Plan trips, flights and hotels
URL
`https://www.expedia.com/mcp`
[Fever Event Discovery](https://developer.feverup.com/)
Discover live entertainment events worldwide
URL
`https://data-search.apigw.feverup.com/mcp`
[FMP](https://financialmodelingprep.com/developer/docs/mcp-server?utm_source=claude)
Comprehensive financial market data
URL
`https://financialmodelingprep.com/mcp`
[G2](https://documentation.g2.com/docs/g2-mcp-server)
Bring real buyer signals into AI workflows
URL
`https://mcp.g2.com/mcp`
[Monte Carlo](https://docs.getmontecarlo.com/docs/mcp-server)
Data & AI observability
URL
`https://mcp.getmontecarlo.com/mcp`
[Glean](https://docs.glean.com/administration/platform/mcp/about)
Bring enterprise context to Claude and your AI tools
Requires user-specific URL. [Get your URL here](https://docs.glean.com/administration/platform/mcp/about)
[Glovo](https://glovoapp.com/docs/en/legal/mcp/)
Anything delivered in minutes
URL
`https://api.glovoapp.com/discovery-mcp/mcp`
[GoCardless](https://developer.gocardless.com/developer-tools/mcp/)
Build GoCardless payment API integrations
URL
`https://mcp.gocardless.com`
[GoDaddy](https://developer.godaddy.com/mcp)
Search domains and check availability
URL
`https://api.godaddy.com/v1/domains/mcp`
[Goodnotes](https://www.notion.so/goodnotes-team/Goodnotes-MCP-Server-Documentation-320b740273d28187a23ad52780a37620)
Turn AI insights into documents
URL
`https://claude-mcp-api.ml.goodnotes.com/mcp`
[Google Cloud BigQuery](https://cloud.google.com/bigquery/docs/use-bigquery-mcp)
BigQuery: Advanced analytical insights for agents
URL
`https://bigquery.googleapis.com/mcp`
[Google Compute Engine](https://cloud.google.com/docs)
MCP server for Google Compute Engine
URL
`https://compute.googleapis.com/mcp`
[Google Calendar](https://developers.google.com/workspace/calendar)
Manage your schedule and coordinate meetings effortlessly
URL
`https://calendarmcp.googleapis.com/mcp/v1`
[Google Drive](https://developers.google.com/workspace/drive)
Search, read, and upload files instantly
URL
`https://drivemcp.googleapis.com/mcp/v1`
[Gmail](https://developers.google.com/workspace/gmail)
Draft replies, summarize threads, & search your inbox
URL
`https://gmailmcp.googleapis.com/mcp/v1`
[GovTribe](https://docs.govtribe.com/user-guide/integrations/govtribe-mcp)
Search government procurement & spending data
URL
`https://govtribe.com/mcp`
[Grain](https://developers.grain.com/mcp)
Put your meetings to work
URL
`https://api.grain.com/_/mcp`
[Granted](https://grantedai.com/mcp)
Discover every grant opportunity in existence.
URL
`https://grantedai.com/api/mcp/mcp`
[Guidepoint](https://clapi-developer.guidepoint.io/mcp/docs)
Real-time access to trusted expert knowledge
URL
`https://clapi.guidepoint.io/mcp-server/v1/mcp`
[Gusto](https://docs.gusto.com/app-integrations/docs/mcp)
Query and analyze your Gusto data
URL
`https://mcp.api.gusto.com/anthropic`
[Phoenix by HG Insights](https://phoenix.hginsights.com/docs/intro)
AI-powered B2B data intelligence & analytics
URL
`https://phoenix.hginsights.com/api/ai/mcp`
[HubSpot](https://knowledge.hubspot.com/integrations/set-up-and-use-the-hubspot-connector-for-claude)
Chat with your CRM data to get personalized insights
URL
`https://mcp.hubspot.com/anthropic`
[IBISWorld](https://help.ibisworld.com/en/articles/14627556-ibisworld-mcp-server-documentation)
Financials, risk data and analysis on 50,000 industries
URL
`https://mcp.ibisworld.com`
[Interactive Brokers (IBKR)](https://www.interactivebrokers.com/lib/cstools/faq/#/content/1442566213)
Trade, invest, analyze, and manage global markets
URL
`https://api.ibkr.com/v1/api/mcp`
[ICE Data Services](https://www.ice.com/ieoauoau)
Analyze U.S. fixed income trade and reference data
URL
`https://fids-mcp.ice.com/mcp`
[IFTTT](https://ift.tt/ai_assistants)
Connect, control, and automate 1,000+ apps with IFTTT
URL
`https://ifttt.com/mcp`
[Medidata](https://learn.medidata.com/en-US/bundle/mcp-server-documentation/page/medidata_mcp_server_documentation.html)
Clinical trial software and site ranking tools
URL
`https://mcp.imedidata.com/mcp`
[Indeed](https://docs.indeed.com/mcp)
Search for jobs on Indeed
URL
`https://mcp.indeed.com/claude/mcp`
[Instacart](https://docs.instacart.com/mcp_servers/)
Groceries and more delivered as fast as 30 minutes
URL
`https://fig-mcp.instacart.com/mcp`
[Intercom](https://developers.intercom.com/docs/guides/mcp)
Access to Intercom data for better customer insights
URL
`https://mcp.intercom.com/mcp`
[Intuit Mailchimp](https://mailchimp.com/help/use-mailchimp-connector-claude)
Create marketing campaigns
URL
`https://ai-inc.mailchimp.com/claude/mcp/v2`
[Intuit QuickBooks](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
`https://ai-inc.quickbooks.intuit.com/v1/mcp`
[Intuit TurboTax](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
`https://ai-inc.turbotax.intuit.com/358A1C1B-F73B-46A7-B130-4B14916E6843/v1/mcp`
[Ironclad Contracts](https://support.ironcladapp.com/hc/en-us/articles/39887091143319-Ironclad-MCP-Server)
Plain language search for faster contract answers
[Jentic](https://docs.jentic.com/guides/mcp/remote-mcp/)
One connection to access all your tools securely
URL
`https://api.jentic.com/mcp`
[PlayMCP](https://www.notion.so/2189b97b4888803dbbdcef264e7eff58)
Connect and use PlayMCP servers in your toolbox
URL
`https://playmcp.kakao.com/mcp`
[S&P Global](https://docs.kensho.com/llmreadyapi/mcp)
Query a range of S&P Global datasets
URL
`https://kfinance.kensho.com/integrations/mcp`
[Ketryx](https://docs.ketryx.com/reference/ketryx-mcp-server)
Search and explore regulated software lifecycle data
URL
`https://app.ketryx.com/api/mcp`
[Kiwi.com](https://mcp-install-instructions.alpic.cloud/servers/kiwi-com-flight-search)
Search flights in Claude
URL
`https://mcp.kiwi.com`
[Klaviyo](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server)
Report, strategize & create with real-time Klaviyo data
URL
`https://mcp.klaviyo.com/mcp?include-mcp-app=true`
[lastminute.com](https://mcp.lastminute.com/docs)
Search, compare and book flights, dynamic packages (flight + hotel) and hotels across global airlines and hotel suppliers.
URL
`https://mcp.lastminute.com/mcp`
[Legal Data Hunter](https://legaldatahunter.com/docs)
Search 23M+ legal docs in 160+ jurisdictions.
URL
`https://legaldatahunter.com/mcp`
[LILT](https://support.lilt.com/kb/LILT-mcp)
High-quality translation with human verification
URL
`https://mcp.lilt.com/mcp`
[Local Falcon](https://github.com/local-falcon/mcp)
AI visibility and local search intelligence platform
URL
`https://mcp.localfalcon.com`
[LSEG](https://www.lseg.com/en/solutions/ai-finance-solutions/anthropic)
Access best in class data & analytics across a broad spectrum of asset classes.
URL
`https://api.analytics.lseg.com/lfa/mcp/server-cl`
[Lumin](https://github.com/luminpdf/lumin-mcp-server)
Manage documents, send signature requests, and convert Markdown to PDF
URL
`https://mcp.luminpdf.com/mcp`
[Lusha](https://docs.lusha.com/mcp-docs)
Find and enrich B2B contacts and companies
URL
`https://mcp.lusha.com/mcp/claude`
[Magic Patterns](https://www.magicpatterns.com/docs/documentation/features/mcp-server/overview)
Discuss and iterate on Magic Patterns designs
URL
`https://mcp.magicpatterns.com/mcp`
[MailerLite](https://developers.mailerlite.com/mcp/#how-mcp-works)
Turn Claude into your email marketing assistant
URL
`https://mcp.mailerlite.com/mcp`
[Make](https://developers.make.com/mcp-server/)
Run Make scenarios and manage your Make account
URL
`https://mcp.make.com`
[Malwarebytes](https://help.malwarebytes.com/hc/en-us/articles/47985341083675-Using-Malwarebytes-in-Claude)
Check links, phones, and emails for scams
URL
`https://scamguard.malwarebytes.com/claude/mcp`
[Melon](https://tech.kakaoent.com/ai/using-melon-mcp-server-en/)
Browse music charts & your personalized music picks
URL
`https://mcp.melon.com/mcp/`
[Mercury](https://docs.mercury.com/docs/connecting-mercury-mcp)
Search, analyze and understand your finances on Mercury
URL
`https://mcp.mercury.com/mcp`
[Metabase](https://www.metabase.com/docs/latest/ai/mcp)
Query and explore your Metabase data
Requires user-specific URL. [Get your URL here](https://www.metabase.com/docs/latest/ai/mcp)
[Microsoft Learn](https://learn.microsoft.com/en-us/training/support/mcp)
Search trusted Microsoft docs to power your development
URL
`https://learn.microsoft.com/api/mcp`
[Mintlify](https://www.mintlify.com/docs/ai/mintlify-mcp)
Search, read, and edit your documentation
URL
`https://mcp.mintlify.com`
[Mixpanel](https://docs.mixpanel.com/docs/features/mcp)
Analyze, query, and manage your Mixpanel data
URL
`https://mcp.mixpanel.com/mcp`
[Moody's](https://www.moodys.com/web/en/us/genai/model-context-protocol.html)
Risk insights, analytics, and decision intelligence
URL
`https://api.moodys.com/genai-ready-data/m1/mcp`
[Morningstar](https://developer.morningstar.com/direct-web-services/documentation/mcp-server/morningstar-mcp-server)
Up-to-date investment and market insights
URL
`https://mcp.morningstar.com/mcp`
[MotherDuck](https://motherduck.com/docs/sql-reference/mcp/)
Get answers from your data
URL
`https://api.motherduck.com/mcp`
[Motion Creative Analytics](https://help.motionapp.com/en/articles/14315735-motion-mcp)
Analyze your Meta ad creative & competitor ad libraries
URL
`https://projects.motionapp.com/mcp`
[MSCI](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
`https://mcp.msci.com/mcp/v1.0/mcp`
[NetSuite](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7200233106.html)
Connect Claude to NetSuite data for analysis & insights
Requires user-specific URL. [Get your URL here](https://system.netsuite.com/mcp/mcpinfo.nl)
[Owkin](https://docs.owkin.com/core-features-and-usage)
Interact with AI agents built for biology
URL
`https://mcp.k.owkin.com/mcp`
[PagerDuty](https://developer.pagerduty.com/docs/mcp-tooling-remote-server)
Manage incidents, services and on-call schedules
URL
`https://mcp.pagerduty.com/mcp`
[PandaDoc](https://developers.pandadoc.com/docs/how-to-use-the-pandadoc-mcp-server)
Create, send, sign and track documents
URL
`https://mcp.pandadoc.com/v1/mcp`
[Pigment](https://kb.pigment.com/docs/mcp-server)
Analyze business data
Requires user-specific URL. [Get your URL here](https://kb.pigment.com/docs/mcp-server)
[PitchBook Premium](https://help.pitchbook.com/s/article/PitchBook-Premium-for-Claude-by-Anthropic)
PitchBook data, embedded in the way you work.
URL
`https://premium.mcp.pitchbook.com/mcp`
[Polar Analytics](https://intercom.help/polar-app/en/collections/17268490-polar-mcp)
Bring all your data in one place & connect it to Claude
URL
`https://api.polaranalytics.com/mcp`
[Postman](https://github.com/postmanlabs/postman-mcp-server)
Give API context to your coding agents
URL
`https://mcp.postman.com/minimal`
[Privacy.com](https://developers.privacy.com/docs/mcp-server)
Manage virtual cards and track your spending patterns
URL
`https://mcp.privacy.com`
[Quartr](https://mcp.quartr.com/docs)
Financial data and AI infrastructure for company research.
URL
`https://mcp.quartr.com/mcp`
[Quo](https://support.quo.com/core-concepts/integrations/mcp)
Surface call insights and missed opportunities
URL
`https://mcp.quo.com/mcp`
[Ramp](https://docs.ramp.com/developer-api/v1/guides/ramp-mcp-remote)
Search, access, and analyze your Ramp financial data
URL
`https://ramp-mcp-remote.ramp.com/mcp`
[Ramp Data](https://docs.ramp.com/developer-api/v1/ramp-data)
Search and analyze Ramp spend across 50,000+ businesses
URL
`https://mcp.ramp.com/ramp-data/anthropic/mcp`
[Bigdata.com](https://docs.bigdata.com/mcp-reference)
Access real-time financial data
URL
`https://mcp.bigdata.com/`
[Razorpay](https://razorpay.com/docs/mcp-server/?preferred-country=IN)
Turn Claude into your Razorpay Dashboard Assistant
URL
`https://mcp.razorpay.com/mcp`
[Resy](https://www.americanexpress.com/content/dam/amex/en-us/credit-cards/benefits/resy/resy_mcp_app_claude.pdf)
Find and book restaurants instantly
URL
`https://apigw.americanexpress.com/dining/v1/mcp`
[Retool](https://docs.retool.com/education/labs/resources/mcp)
Build production apps and manage Retool with AI agents
Requires user-specific URL. [Get your URL here](https://docs.retool.com/education/labs/resources/mcp)
[Rillet](https://docs.api.rillet.com/docs/mcp)
Query your live GL and financials in plain English
URL
`https://api.rillet.com/mcp`
[SandboxAQ](https://docs.aisim.sandboxaq.com/)
Large Quantitative Models for scientific discovery
Requires user-specific URL. [Get your URL here](https://docs.aisim.sandboxaq.com/)
[Semrush](https://developer.semrush.com/api/introduction/semrush-mcp/)
SEO, market data, and brand visibility insights
URL
`https://mcp.semrush.com/claude/v1/mcp`
[Shopify](https://help.shopify.com/en/manual/apps/connecting-ai-tools)
Build, manage, and analyze your Shopify store
URL
`https://setup.shopify.com/mcp`
[Sigma](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
Query, search, and explore your data with Sigma
Requires user-specific URL. [Get your URL here](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
[SignNow](https://docs.signnow.com/docs/signnow/mcp-server)
Automate eSignature workflows directly from Claude
URL
`https://mcp-server.signnow.com/mcp`
[Similarweb](https://docs.similarweb.com/api-v5/mcp/mcp-setup)
Real time web, mobile app, and market data.
URL
`https://mcp.similarweb.com`
[Trimble SketchUp](https://help.sketchup.com/en/sketchup-claude-connector)
Create and iterate 3D models for use in SketchUp
URL
`https://api.sketchup.com/mcp/v1/sketchup/mcp`
[Slack](https://docs.slack.dev/ai/mcp-server)
Send messages, create canvases, and fetch Slack data
URL
`https://mcp.slack.com/mcp`
[Smartsheet](https://help.smartsheet.com/articles/2483663-use-smartsheet-connector-claude)
Analyze and manage Smartsheet data with Claude
Requires user-specific URL. [Get your URL here](https://help.smartsheet.com/articles/2483656-install-smartsheet-connector-claude#toc-get-started)
[Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
Retrieve both structured and unstructured data
Requires user-specific URL. [Get your URL here](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)
[Solve Intelligence](https://api.solveintelligence.com/guide/mcp/intro/)
Search, draft, and chart patents
URL
`https://api.solveintelligence.com/mcp/`
[Sourcegraph](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
Give Claude full enterprise-scale codebase context.
Requires user-specific URL. [Get your URL here](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
[Splice](https://support.splice.com/en/articles/14442749-getting-started-with-the-splice-mcp-server-beta)
Search Splice's sounds catalog, build stacks & more!
URL
`https://mcp.splice.com/mcp`
[Spotify](https://support.spotify.com/)
Music and podcast recommendations, just for you.
URL
`https://mcp-gateway-external-pilot.spotify.net/mcp`
[AdisInsight](https://adisinsight-mcp.springer.com)
Pharmaceutical drug & clinical trial intelligence
URL
`https://adisinsight-mcp.springer.com/mcp`
[Order by Cash App](https://goose-docs.ai/docs/mcp/cash-app-mcp/)
Discover local food spots and order with a conversation
URL
`https://connect.squareup.com/v2/mcp/cash-app`
[Square](https://developer.squareup.com/docs/mcp)
Search and manage transaction, merchant, and payment data
URL
`https://mcp.squareup.com/sse`
[StubHub](https://support.stubhub.com/articles/61000310240-using-stubhub-in-chatgpt-and-claude)
Find tickets on the World's Largest Ticket Marketplace
URL
`https://open-ai-app.stubhub.net/mcp`
[Superhuman Mail](https://help.superhuman.com/hc/en-us/articles/49810745762067-Superhuman-Mail-MCP-Server-Beta)
The most productive email app ever, for Gmail & Outlook
URL
`https://mcp.mail.superhuman.com/mcp`
[Supermetrics Marketing Analytics](https://mcp.supermetrics.com/docs)
Google Ads, Facebook Ads & 200+ marketing platforms
URL
`https://mcp.supermetrics.com/mcp`
[SurveyMonkey](https://www.surveymonkey.com/apps/BKcduxPnkCN4NFCRokUYCw_3D_3D/details/)
Design surveys, collect responses, and analyze results
URL
`https://mcp.surveymonkey.com/mcp`
[Taskrabbit Booking Assistance](https://docs.google.com/document/d/1tWm33lJx4JdwN-Joqk7vydxQHaRGLod68wdS4k_hY9w/edit?tab=t.edb6z98lya3r#heading=h.2j0sep9c1ren)
Find & book local Taskrabbit services near you
URL
`https://mcp.taskrabbit.com/mcp`
[Tavily](https://docs.tavily.com/documentation/mcp)
Connect your AI agents to the web
URL
`https://mcp.tavily.com/mcp`
[Third Bridge](https://www.thirdbridge.com/en-us/data-solutions/mcp)
Expert-led enhanced insights
URL
`https://ai.thirdbridge.com/mcp/sse`
[CoCounsel Legal](https://legal-mcp.thomsonreuters.com/docs/connector-guide)
Thomson Reuters CoCounsel Legal, in Claude
URL
`https://legal-mcp.thomsonreuters.com/mcp`
[Thumbtack](https://docs.google.com/document/d/1RmGske5ktjAi9d7Ayok_yOv3a6Z2RDBSxIlX7aC5OEM/edit?usp=sharing)
Find and hire local pros in Claude
URL
`https://mcp.thumbtack.com/mcp`
[Tines](https://www.tines.com/docs/actions/templates/mcp-server/)
Securely deploy servers in a matter of seconds in Tines
Requires user-specific URL. [Get your URL here](https://www.tines.com/docs/actions/templates/mcp-server/)
[tldraw](https://tldraw.notion.site/tldraw-mcp-app)
Let Claude sketch, draw, and diagram with you
URL
`https://tldraw-mcp-app.tldraw.workers.dev/mcp`
[Tripadvisor](https://www.tripadvisor.com)
Find your perfect hotel based on Tripadvisor reviews
URL
`https://production.ai-mcp-extensibility-prd.tamg.cloud/ogMvjY4De1G7CiHanMOAgddl/mcp`
[Turkish Airlines](https://mcp.turkishtechlab.com/)
Search flights, plan trips, and manage bookings
URL
`https://mcp-app.turkishtechlab.com/mcp`
[Twilio](https://www.twilio.com/docs/ai/mcp)
Build powerful communications and customer engagement
URL
`https://mcp.twilio.com/docs`
[Uber](https://www.uber.com/legal/en/)
Get Uber price & time estimates for any ride option
URL
`https://mcp.uber.com/claude/rides-3p/mcp`
[Uber Eats](https://www.ubereats.com)
Explore restaurants and dishes
URL
`https://mcp.ubereats.com/eats-claude/mcp`
[Udemy Business](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
`https://api.udemy.com/mcp`
[Pylon](https://support.usepylon.com/articles/2407390554-connecting-to-the-pylon-mcp-server?lang=en)
Search and manage Pylon support issues
URL
`https://mcp.usepylon.com/`
[Verisk Underwriting Intelligence](https://www.verisk.com/resources/verisk-underwriting-intelligence/)
Ask questions. Get underwriting insights from Verisk.
URL
`https://gatewaymcp.verisk.com/underwriting/intelligencemcp/v1`
[Verisk XactRestore](https://veriskpropertyestimatingsolutions.my.site.com/s/article/2622)
Natural-language estimating for XactRestore
URL
`https://xactrestore-xactremodelserver-usw2-prod.propsol.io/mcp`
[Viator](https://docs.viator.com/partner-api/mcp/)
Book travel experiences around the world
URL
`https://exp-app-mcp.prod.ep.viator.com/mcp`
[Visier](https://docs.visier.com/developer/agents/mcp/mcp-server.htm)
Find people, productivity and business impact insights
Requires user-specific URL. [Get your URL here](https://docs.visier.com/developer/agents/mcp/mcp-server-set-up.htm)
[Webflow](https://developers.webflow.com/mcp/v1.0.0/reference/overview)
Manage Webflow CMS, pages, assets and sites
URL
`https://mcp.webflow.com/mcp`
[Wolfram](https://www.wolfram.com/artificial-intelligence/mcp-service/)
Inject precise, real-time computation and knowledge
URL
`https://agenttools.wolfram.com/mcp`
[WordPress.com](https://developer.wordpress.com/docs/mcp/)
Secure AI access to manage your WordPress.com sites
URL
`https://public-api.wordpress.com/wpcom/v2/mcp/v1`
[Workable](https://workable.readme.io/reference/workable-mcp-server)
Your AI assistant for Hiring and HR — inside Workable
URL
`https://mcp.workable.com/mcp`
[Workato](https://docs.workato.com/en/mcp.html)
Automate workflows and connect your business apps
Requires user-specific URL. [Get your URL here](https://app.workato.com/ai_hub/mcp)
[Wyndham Hotels and Resorts](https://www.wyndhamhotels.com/mcp-doc)
Discover the right Wyndham Hotel for you, faster
URL
`https://mcp.wyndhamhotels.com/claude/mcp`
[Xero](https://central.xero.com/s/article/Connect-Xero-using-the-Xero-connector-in-Claude?userregion=true)
Access your Xero financials from any conversation
URL
`https://mcp.xero.com/mcp`
[Yardi Virtuoso](https://help.virtuoso.ai/en/articles/13679727-yardi-virtuoso-mcp-technical-documentation-guide)
Real-time Yardi data & insights
URL
`https://mcp.virtuoso.ai/mcp`
[Zapier](https://docs.zapier.com/mcp/home)
Automate workflows across thousands of apps via conversation
URL
`https://mcp.zapier.com/api/v1/connect`
[ZipRecruiter](https://api.ziprecruiter.com/mcp/docs)
Job search made easy
URL
`https://api.ziprecruiter.com/mcp`
[Zoho Books](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](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](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](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](https://docs.zoominfo.com/docs/zi-api-mcp-overview/)
Enrich contacts & accounts with GTM intelligence
URL
`https://mcp.zoominfo.com/mcp`
[Tango](https://tango.makegov.com/docs/mcp/)
Search for US Government Contracting Data
URL
`https://govcon.dev/mcp`
[Jam](https://jam.dev/docs/debug-a-jam/mcp)
Record screen and collect automatic context for issues
URL
`https://mcp.jam.dev/mcp`
[Sentry](https://docs.sentry.io/product/sentry-mcp/)
Search, query, and debug errors intelligently
URL
`https://mcp.sentry.dev/mcp`
[Stytch](https://stytch.com/docs/workspace-management/stytch-mcp)
Manage your Stytch Project
URL
`https://mcp.stytch.dev/mcp`
[Craft](https://documents.craft.me/jWeCVJrSfxFRuA)
Notes & second brain
URL
`https://mcp.craft.do/my/mcp`
[Alma](https://alma.food/mcp)
Your nutrition data, inside every Claude conversation.
URL
`https://mcp.alma.food`
[MoSPI](https://www.datainnovation.mospi.gov.in/mospi-mcp)
India's official statistics via natural language
URL
`https://mcp.mospi.gov.in/`
[Adobe for creativity](https://developer.adobe.com/adobe-for-creativity/)
Ideate, create, and deliver with Adobe pro tools
URL
`https://adobe-creativity.adobe.io/mcp`
[Adobe Journey Optimizer](https://experienceleague.adobe.com/en/docs/journey-optimizer/using/content-management/combine/ajo-mcp)
Understand and troubleshoot your Journeys and Campaigns
URL
`https://ajo-mcp.adobe.io/mcp`
[Adobe Marketing Agent](https://acrobat.adobe.com/id/urn:aaid:sc:AP:5799e952-be87-4829-b0c4-6f82ca8e8b8b)
Marketing campaign and audience insights from Adobe
URL
`https://aep-ai-ama.adobe.io/mcp`
[Common Room](https://www.commonroom.io/docs/using-common-room/common-room-for-claude-connector-and-plugin/)
Your GTM Copilot
URL
`https://mcp.commonroom.io/mcp`
[Customer.io](https://docs.customer.io/ai/mcp-server/)
Explore customer data and generate insights via Claude
Requires user-specific URL. [Get your URL here](https://docs.customer.io/ai/mcp-server/)
[Eraser](https://docs.eraser.io/docs/mcp)
Generate, manage, and update Eraser diagrams and files
URL
`https://app.eraser.io/api/mcp`
[Harness.io](https://github.com/harness/mcp-server)
Build, Ship and Secure your apps on Harness Platform
URL
`https://mcp.harness.io/mcp`
[Honeycomb](https://docs.honeycomb.io/troubleshoot/product-lifecycle/beta/mcp/)
Query and explore observability data and SLOs
URL
`https://mcp.honeycomb.io/mcp`
[incident.io](https://docs.incident.io/ai/remote-mcp)
See and manage everything in incident.io
URL
`https://mcp.incident.io/mcp`
[n8n](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
Access and run your n8n workflows
Requires user-specific URL. [Get your URL here](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
[Pendo](https://support.pendo.io/hc/en-us/articles/41102236924955)
Connect to Pendo for product and user insights
Requires user-specific URL. [Get your URL here](https://support.pendo.io/hc/en-us/articles/41102236924955)
[Sanity](https://www.sanity.io/docs/ai/mcp-server)
Create, query, and manage structured content in Sanity
URL
`https://mcp.sanity.io`
[Starburst](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
Securely retrieve data from your federated data sources
Requires user-specific URL. [Get your URL here](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
[tldv](https://tldv.notion.site/tl-dv-MCP-Official-Documentation-330cce15f3ba80638f5ac0253e3b8fd4?source=copy_link)
Fetch Transcripts & Notes from Meet, Zoom & Teams
URL
`https://mcp.tldv.io/mcp`
[Tropic](https://help.tropicapp.io/hc/en-us/articles/45502083594267-Using-Model-Context-Protocol-MCP-with-Tropic)
Save money on Software + AI contracts
URL
`https://app.tropicapp.io/mcp`
[Unthread](https://docs.unthread.io/docs/unthread-ai/unthread-mcp)
Manage and automate your support tickets
URL
`https://app.unthread.io/api/mcp`
[Zocks](https://help.zocks.io/en/articles/14075856-connect-to-the-zocks-mcp-server)
Analyze client conversations, patterns, and insights.
URL
`https://mcp.zocks.io/v1/mcp`
[Trellis](https://support.trellis.law)
Claude for Trial Court Litigators
URL
`https://mcp.trellis.law/anthropic`
[Todoist](https://github.com/Doist/todoist-ai)
Search, complete, and manage your tasks in Todoist
URL
`https://ai.todoist.net/mcp`
[Relativity](https://help.relativity.com/topic.html?t=GLJ39)
Organize Data. Discover the Truth. Act on It.
Requires user-specific URL. [Get your URL here](https://help.relativity.com/topic.html?t=GLJ39)
[BoardWise](https://boardwise.online/mcp)
Calm board-defense guidance for licensed pros.
URL
`https://uakozrqrztgrgwoywxkx.supabase.co/functions/v1/mcp-server`
[Candid](https://support.claude.com/en/articles/12923235-using-the-candid-connector-in-claude)
Research nonprofits and funders using Candid's data
URL
`https://mcp.candid.org/mcp`
[Learning Commons Knowledge Graph](https://docs.learningcommons.org/knowledge-graph/integrations/claude)
K-12 standards, skills, and learning progressions
URL
`https://kg.mcp.learningcommons.org/mcp`
[Open Targets](https://github.com/opentargets/open-targets-platform-mcp)
Drug target discovery and prioritisation platform
URL
`https://mcp.platform.opentargets.org/mcp`
[Synapse.org](https://github.com/susheel/synapse-mcp?tab=readme-ov-file#synapse-mcp-server)
Search and metadata tools for Synapse scientific data
URL
`https://mcp.synapse.org/mcp`
[Chronograph](https://lp-help.chronograph.pe/article/735-chronograph-mcp)
Interact with your Chronograph data directly in Claude
URL
`https://ai.chronograph.pe/mcp`
[Hex](https://learn.hex.tech/docs/administration/mcp-server)
Answer questions with the Hex agent
Requires user-specific URL. [Get your URL here](https://learn.hex.tech/docs/administration/mcp-server#connect-to-claude)
[Zoom for Claude](https://developers.zoom.us/docs/mcp/zoom/)
Search, recap, and act on your Zoom meetings
URL
`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.
---
*Truncated: 1545 more documents not shown (size limit)*