> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/ai-coding-tool-integrations/codex-integration.md). # Codex integration Enabling Codex metrics Read more about Swarmia's other [AI coding tool integrations](/settings/integrations/ai-coding-tool-integrations.md) and [understanding the impact of AI tools](/guides/understand-the-impact-of-ai-tools.md). Swarmia reads Codex usage from the [Codex Enterprise Analytics API](https://chatgpt.com/public/admin/api-reference), which is available on ChatGPT Enterprise. [Codex Business isn't supported yet](#why-isnt-codex-business-supported). ## Enabling Codex metrics You need two things from ChatGPT: your workspace ID and an admin key that can read the workspace's Codex analytics. ### 1. Find your workspace ID Open the [ChatGPT admin console](https://chatgpt.com/admin) and find the **Workspace ID** from the workspace settings page. You need the ChatGPT admin or Codex admin role. ### 2. Create an admin key In the [OpenAI admin console](https://admin.openai.com), go to **Credentials → Admin keys** and click **Create new admin key**: * Choose the workspace you copied the ID from. * Under permissions, select **Restricted** and add three read scopes: * `codex.enterprise.analytics.read` * `chatgpt.enterprise.usage_limit.read` * `enterprise.analytics.usage.read` (shown as **Enterprise analytics API**) The key is shown only once, so copy it before closing the dialog. ### 3. Connect Codex in Swarmia Paste the workspace ID and the admin key into [Settings → AI tools → Codex](https://app.swarmia.com/settings/ai-assistants) and click **Apply**. You need the [organization admin](/settings/organization/managing-users-and-roles.md) role. We fetch 180 days of historical activity data upon connection. {% hint style="info" %} [Cloud agent](/features/ai-tools/cloud-agents.md) pull requests opened by the Codex GitHub connector and [reviews](/features/ai-tools/review-agents.md) left by Codex are detected from your existing pull request data, so they show up whether or not you connect the analytics API. {% endhint %} ## Where Codex data shows up Once connected, Codex appears alongside your other AI tools in: * [AI adoption](/features/ai-tools/ai-adoption.md), as weekly active users per person and team. * [AI tool detection & filters](/features/ai-tools/ai-tool-detection-and-filters.md), which tags the pull requests Codex worked on. * [AI impact: Code](/features/ai-tools/ai-impact-code.md), where you can compare Codex-assisted pull requests against the rest. * [AI cost](/features/ai-tools/ai-cost.md), as AI token usage from Codex per person, team, and work item. Codex doesn't have a dedicated activity breakdown page yet. ## Frequently asked questions ### Why isn't Codex Business supported? The Codex Enterprise Analytics API is only available on ChatGPT Enterprise. We're working on a way to measure Codex usage on Business workspaces. Email to join the waitlist. Pull requests from the Codex cloud agent and reviews from Codex are detected from your pull request data, so those work on any plan. ### Why do you need an admin key? Isn't that a bit excessive? We build our integrations with the principle of least privilege. The Codex Enterprise Analytics API is only reachable with an admin key, but you can restrict the one you give us to a single workspace and three read scopes: `codex.enterprise.analytics.read`, `chatgpt.enterprise.usage_limit.read`, and `enterprise.analytics.usage.read`. You can [read more about our data access here](/resources/security-and-data-retention/data-access.md#codex-integration). ### Why doesn't anyone show up as idle in AI adoption? The Codex Enterprise Analytics API reports usage, not seats, so Swarmia can't tell a person who has a Codex seat and doesn't use it apart from someone who has no seat at all. For Codex, [*enabled users*](/features/ai-tools/ai-adoption.md) only include *active users*, and idle seats aren't shown. The same limitation applies to [Claude Code OpenTelemetry monitoring](/settings/integrations/ai-coding-tool-integrations/claude-code-integration.md#opentelemetry-monitoring). ### Why is a Codex review missing from a pull request? Swarmia counts a Codex review only when Codex leaves inline findings. Read more about [why a Codex review can be missing](/features/ai-tools/review-agents.md#why-is-a-codex-review-missing-from-a-pull-request). ### Why doesn't someone's Codex usage show up under their name? Swarmia creates a Codex identity from the Codex user ID and, when the API reports one, the email address. Identities are merged into the right author by email, so an account without an email or with one that doesn't match the person's other identities stays separate. Fix it on the [Authors](/settings/organization/contributors.md#move-or-remove-an-account) page by moving the Codex account to the person's author. ### Can I connect more than one Codex workspace? No. Swarmia connects one ChatGPT workspace per organization, and the workspace ID is locked once it's set. Contact us at to connect a different workspace. ### How long does it take for Codex data to show up? The first sync starts as soon as you connect, so your history lands shortly after. After that, Codex usage is synced daily, so new activity shows up within a day. ### What happens if I disable the integration? Swarmia stops syncing new data and keeps everything it has already collected. Reconnecting the same workspace continues the sync from where it left off. If your admin key stops working, for example because it expired or was revoked, Swarmia disables the integration the same way and emails your [organization admins](/settings/organization/managing-users-and-roles.md) so you can reconnect. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.swarmia.com/settings/integrations/ai-coding-tool-integrations/codex-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.