> 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 with the Codex Enterprise Analytics API or OpenTelemetry monitoring

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).

There are two ways to get Codex usage into Swarmia, and which ones you can use depends on how your engineers use Codex. For a quick overview, see the table below. You can go to [Settings → AI tools → Codex](https://app.swarmia.com/settings/ai-assistants), click "Add new", and Swarmia guides you through the setup.

|                                     | <p><strong>ChatGPT Business</strong></p><p>(Usage included per seat)</p> | <p><strong>ChatGPT Enterprise</strong></p><p>(Per-seat limits or a shared credit pool)</p> | <p><strong>API key</strong></p><p>(Usage billed at API rates)</p> | <p><strong>3rd-party platform</strong></p><p>(Amazon Bedrock, Azure OpenAI, LiteLLM)</p> |
| ----------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Codex Enterprise Analytics API**  | :x: Not available                                                        | :white\_check\_mark: Recommended                                                           | :x: Not available                                                 | :x: Not available                                                                        |
| **OpenTelemetry monitoring** (beta) | :white\_check\_mark: Recommended                                         | :heavy\_check\_mark: Available                                                             | :white\_check\_mark: Recommended                                  | :white\_check\_mark: Recommended                                                         |

You can use both options in the same Swarmia workspace. For example, you can connect the Codex Enterprise Analytics API for your Enterprise workspace and add OpenTelemetry monitoring for engineers who use an API key. Swarmia deduplicates overlapping activity so the same usage is not counted twice.

{% 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 Codex.
{% endhint %}

## Codex Enterprise Analytics API

{% hint style="info" %}
Codex Enterprise Analytics API availability:

* :x: ChatGPT Business
* :white\_check\_mark: ChatGPT Enterprise
* :x: API key
* :x: 3rd-party platform
  {% endhint %}

Swarmia reads Codex usage from the [Codex Enterprise Analytics API](https://chatgpt.com/public/admin/api-reference). 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

In [Settings → AI tools → Codex](https://app.swarmia.com/settings/ai-assistants), click "Add new", select **ChatGPT Enterprise**, paste the workspace ID and the admin key, 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="warning" %}
The Codex Enterprise Analytics API option has these limitations:

* **Metrics lag by about a day:** Codex usage is synced daily.
* **No data on idle users:** The API reports usage, not seats, so there's no visibility into people who have a seat but are not using it. Consequently, [*enabled users*](/features/ai-tools/ai-adoption.md) only include *active users*.
  {% endhint %}

## OpenTelemetry monitoring

{% hint style="info" %}
OpenTelemetry monitoring for Codex is in beta testing. Contact us at <hello@swarmia.com> to join the beta.

OpenTelemetry monitoring availability:

* :white\_check\_mark: ChatGPT Business
* :white\_check\_mark: ChatGPT Enterprise
* :white\_check\_mark: API key
* :white\_check\_mark: 3rd-party platform
  {% endhint %}

Codex's [OpenTelemetry monitoring](https://learn.chatgpt.com/docs/config-file/config-advanced#observability-and-telemetry) lets each engineer's Codex send usage metrics to Swarmia. It works with any plan or login, and the data shows up in Swarmia within an hour.

The setup has two parts: point Codex at Swarmia, and tell Swarmia whose usage it is. The steps below show the settings for one engineer. To deploy them to everyone, see [Roll out with device management (MDM)](#roll-out-with-device-management-mdm).

### 1. Configure the metrics endpoint

Add the settings below to each engineer's Codex `config.toml`:

* macOS and Linux: `~/.codex/config.toml`
* Windows: `%USERPROFILE%\.codex\config.toml`

```toml
[otel.metrics_exporter.otlp-http]
endpoint = "https://hook.swarmia.com/otel/v1/metrics"
protocol = "json"
headers.Authorization = "<AUTHORIZATION_TOKEN>"
```

Replace `<AUTHORIZATION_TOKEN>` with a key you can generate in [Settings → AI tools → Codex](https://app.swarmia.com/settings/ai-assistants) by clicking "Add new", choosing your plan, and clicking "Click to reveal". It's the same key that Claude Code OpenTelemetry monitoring uses.

These settings only send metrics. They don't send logs or traces, so prompts and code are not included.

{% hint style="info" %}
Codex can also send the metrics to Swarmia through an OpenTelemetry Collector, for example if you already send them to another destination. See [Send metrics through an OpenTelemetry Collector](#send-metrics-through-an-opentelemetry-collector).
{% endhint %}

### 2. Set each engineer's email

Codex metrics don't say who sent them, so Swarmia needs each engineer's email to match the usage to the right author. Add it in one of these ways.

**Option A: Environment variable.**

```sh
OTEL_RESOURCE_ATTRIBUTES="user.email=developer@example.com"
```

Set the variable in the environment that starts Codex, for example in the engineer's shell profile on macOS and Linux, or as a user environment variable on Windows.

**Option B: Header.** The header lives in `config.toml`, so it applies no matter how Codex is started. Add it to the same section in each engineer's `config.toml`:

```toml
[otel.metrics_exporter.otlp-http]
endpoint = "https://hook.swarmia.com/otel/v1/metrics"
protocol = "json"
headers.Authorization = "<AUTHORIZATION_TOKEN>"
headers.X-Swarmia-User-Email = "developer@example.com"
```

The header doesn't reach Swarmia through a [Collector](#send-metrics-through-an-opentelemetry-collector) by default, so use Option A if you use one. If both are set, Swarmia uses the email from the environment variable.

{% hint style="warning" %}
The OpenTelemetry monitoring option has these limitations:

* **No historical backfill:** Swarmia collects the metrics in real time, and there's no way to fetch data from the time before you enabled the integration.
* **No data on idle users:** Swarmia receives only usage data, so there's no visibility into people who have a seat but are not using it. Consequently, [*enabled users*](/features/ai-tools/ai-adoption.md) only include *active users*.
* **Estimated cost:** Codex metrics include token counts but not cost. Swarmia estimates the cost from [Codex's list prices](https://learn.chatgpt.com/docs/pricing). See [AI cost](/features/ai-tools/ai-cost.md) for details.
  {% endhint %}

### Send metrics through an OpenTelemetry Collector

If you already send Codex metrics to another destination, use an OpenTelemetry Collector to receive them once and forward them to both. The setup differs from sending the metrics straight to Swarmia in three ways:

1. **Endpoint:** In the settings from [step 1](#id-1.-configure-the-metrics-endpoint), set `endpoint` to your Collector's metrics endpoint and remove `headers.Authorization`. The Collector adds the token when it forwards the metrics to Swarmia.
2. **Email:** Set the email with the [environment variable](#id-2.-set-each-engineers-email) (Option A). The email is part of the metrics, so the Collector forwards it with them. The header (Option B) doesn't reach Swarmia by default, because the Collector sends its own requests to Swarmia without the headers from Codex's requests.
3. **Collector:** Configure the Collector as described in [Send Claude Code OpenTelemetry metrics to multiple destinations](/settings/integrations/ai-coding-tool-integrations/claude-code-integration/claude-code-otel-collector.md). The guide is written for Claude Code, but the Collector setup is the same, except for how a centralized Collector picks out the metrics to send to Swarmia. Codex reports a different `service.name` depending on how it's started, so filter on the instrumentation scope instead. Use this filter processor in the Swarmia pipeline:

   ```yaml
   processors:
     filter/codex:
       error_mode: ignore
       metrics:
         metric:
           - 'instrumentation_scope.name != "codex"'
   ```

### Roll out with device management (MDM)

For an organization-wide rollout, deploy the settings with your device management tool (MDM, such as Jamf, Kandji, or Intune) instead of asking each engineer to edit their own files.

The endpoint and the authorization token are the same for everyone, so you can deploy them as one shared file. The email is different for each engineer, so deploy it separately.

#### Endpoint settings

Deploy the settings from [step 1](#id-1.-configure-the-metrics-endpoint) as a shared configuration file:

* **macOS and Linux:** `/etc/codex/managed_config.toml`
* **Windows:** `%ProgramData%\OpenAI\Codex\config.toml`

On macOS, you can also deliver the settings as a configuration profile. Read more about [Codex's managed configuration](https://learn.chatgpt.com/codex/enterprise/managed-configuration) and [configuration precedence](https://learn.chatgpt.com/codex/config-file/config-basic#configuration-precedence).

#### Engineer emails

Most MDM tools can fill in the signed-in user's email in scripts or profiles, for example with Jamf's `$EMAIL` payload variable. Use it to deploy one of the email options from [step 2](#id-2.-set-each-engineers-email):

* **Option A:** Set `OTEL_RESOURCE_ATTRIBUTES="user.email=<email>"` in each engineer's environment.
* **Option B:** Write the complete section from Option B, including the email header, into each engineer's `~/.codex/config.toml` with a per-user script.

## 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

### Which option should I use?

If you're on ChatGPT Enterprise, start with the Codex Enterprise Analytics API. It needs no changes on engineers' machines and includes 180 days of history.

Use OpenTelemetry monitoring if:

* You're on ChatGPT Business, or your engineers use Codex with an API key or a 3rd-party platform.
* You want Codex data to show up within an hour instead of the next day.
* You have more than one ChatGPT workspace.
* You'd rather not give Swarmia analytics API access.

### Is Codex Business supported?

Yes, with [OpenTelemetry monitoring](#opentelemetry-monitoring), which is in beta testing. Contact us at <hello@swarmia.com> to join the beta. The Codex Enterprise Analytics API is only available on ChatGPT Enterprise.

Pull requests from the Codex cloud agent and reviews from Codex are detected from your pull request data, so those work on any plan.

### Can I use both options at the same time?

Yes. Swarmia combines them without counting the same usage twice:

* In [AI adoption](/features/ai-tools/ai-adoption.md), a person is active on a day if either option reports Codex usage for them.
* In [AI cost](/features/ai-tools/ai-cost.md), if both options report usage for the same person on the same day, Swarmia uses the Codex Enterprise Analytics API, since it reports OpenAI's own cost estimate.

### Can I connect more than one Codex workspace?

With OpenTelemetry monitoring, yes. The settings live on engineers' machines, so usage from any workspace, plan, or API key is sent to Swarmia.

The Codex Enterprise Analytics API connects one ChatGPT workspace per organization, and the workspace ID is locked once it's set. Contact us at <hello@swarmia.com> to connect a different workspace.

### Codex Enterprise Analytics API: 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`.

If your policies don't allow sharing admin keys, even restricted ones, you can use [OpenTelemetry monitoring](#opentelemetry-monitoring).

You can [read more about our data access here](/resources/security-and-data-retention/data-access.md#codex-integration).

### Codex Enterprise Analytics API: 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.

### Codex Enterprise Analytics API: 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.

### OpenTelemetry monitoring: How long does it take for the data to become visible?

The **Data received** timestamp in [Settings → AI tools → Codex → OpenTelemetry monitoring](https://app.swarmia.com/settings/ai-assistants) shows when Swarmia last received Codex metrics. It can take up to an hour for the data to become visible in metrics.

Codex sends metrics in batches while it runs and when it exits, so a short session can show up only after Codex is closed.

### OpenTelemetry monitoring: Which Codex clients are included?

The Codex CLI, the Codex IDE extension, and the Codex desktop app read the same `config.toml`, so usage from all of them is included.

Codex cloud tasks run on OpenAI's servers and don't use your local settings, so their usage isn't sent. Pull requests the Codex cloud agent opens are still detected from your [pull request data](/features/ai-tools/cloud-agents.md).

### OpenTelemetry monitoring: How is the cost calculated?

Codex metrics include token counts but not cost, so Swarmia estimates it from [Codex's list prices](https://learn.chatgpt.com/docs/pricing):

* Swarmia assumes standard speed, since the metrics don't say whether a faster speed was used.
* Tokens from models that aren't on the price list aren't included in the estimate.
* Plan discounts and included usage aren't taken into account.

If you also connect the Codex Enterprise Analytics API, Swarmia uses OpenAI's own cost estimate for the days it covers.

### OpenTelemetry monitoring: Can I send data to Swarmia and another destination?

Yes, with an OpenTelemetry Collector. See [Send metrics through an OpenTelemetry Collector](#send-metrics-through-an-opentelemetry-collector).

### OpenTelemetry monitoring: Why is a certain user not visible in Swarmia?

Check these first:

* **Email:** The email must be set with one of the [two options](#id-2.-set-each-engineers-email), and it must match the email of the person's author in Swarmia. If it doesn't, you can [move the Codex account to the right author](/settings/organization/authors.md#move-or-remove-an-account).
* **Collector:** If the metrics go through a [Collector](#send-metrics-through-an-opentelemetry-collector), the email header doesn't reach Swarmia by default. Set the email with the environment variable instead.
* **Analytics:** If `[analytics] enabled = false` is set in any `config.toml`, the Codex CLI also turns off custom metrics exporters, including the one that sends data to Swarmia.
* **Environment:** If the email is set with the environment variable, Codex must be started from an environment where the variable is set. For example, a variable set in a shell profile isn't visible to apps started outside that shell.

They can also use this prompt in Codex to help diagnose problems with their configuration:

{% code overflow="wrap" %}

```
Help me verify my Swarmia OpenTelemetry setup for Codex. Work through these in order:

1. Find every Codex config file that applies to me and show which ones exist: ~/.codex/config.toml, /etc/codex/config.toml, /etc/codex/managed_config.toml, and on macOS the managed preferences for com.openai.codex (decode config_toml_base64 if present). On Windows, check %USERPROFILE%\.codex\config.toml and %ProgramData%\OpenAI\Codex\config.toml.

2. Show the resolved [otel.metrics_exporter.otlp-http] settings and which file each value came from. Hide the Authorization header value.

3. Confirm the endpoint is https://hook.swarmia.com/otel/v1/metrics or my expected Collector, and that protocol is "json". For the direct endpoint, test it with a verbose curl request without the Authorization header.

4. Check whether analytics.enabled is set to false anywhere, since that turns off custom metrics exporters in Codex CLI.

5. Check that my email is set, either as user.email in the OTEL_RESOURCE_ATTRIBUTES environment variable or as the X-Swarmia-User-Email header, and show which one is used. If the endpoint is a Collector and the email is only in the header, warn me that it won't reach Swarmia by default.
```

{% endcode %}

### OpenTelemetry monitoring: How do I stop sending data?

Remove the `[otel.metrics_exporter.otlp-http]` settings from the `config.toml` files where you added them. The data Swarmia has already received is kept.

### Why doesn't anyone show up as idle in AI adoption?

Neither option reports 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.

### 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 matches Codex usage to authors by email:

* **Codex Enterprise Analytics API:** Swarmia creates a Codex identity from the Codex user ID and, when the API reports one, the email address.
* **OpenTelemetry monitoring:** Swarmia uses the email you [set for each engineer](#id-2.-set-each-engineers-email).

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/authors.md#move-or-remove-an-account) page by moving the Codex account to the person's author.


---

# 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=<question>&goal=<user_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.