> 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 two read scopes: * `codex.enterprise.analytics.read` * `chatgpt.enterprise.usage_limit.read` 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 the token value of Codex usage 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 two read scopes: `codex.enterprise.analytics.read`, and `chatgpt.enterprise.usage_limit.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 on their contributor? 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 contributor by email, so an account without an email or with one that doesn't match the person's other identities stays separate. Merge it by hand in the [Contributor settings](/settings/organization/contributors.md): search for the person, select both the Codex identity and the contributor, and click **Merge**. ### 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.