> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Connect Codex analytics to Windmill to sync per-user coding agent usage, token consumption, and client-surface breakdowns into team stats and reviews.

> [!WARNING]
>
> Codex's analytics API requires an OpenAI **Admin key**, which is only available for eligible managed ChatGPT workspaces, such as **ChatGPT Enterprise**, **Edu**, or **Healthcare**. You must be on one of these plans to connect this integration.

## Benefits of connecting Codex to Windmill

Connecting Codex to Windmill brings AI coding agent usage directly into stats, performance reviews, and 1:1s — giving managers and engineers visibility into how Codex is being adopted across the team.

* Tracks how engineers are using Codex for autonomous coding tasks across different client surfaces
* Surfaces adoption patterns including thread volume, turn depth, and token consumption without self-reporting
* Helps managers understand AI tool usage and coach their teams on effective workflows
* Provides concrete data for performance conversations about productivity and tool adoption
* Syncs automatically — no manual tracking or surveys required

Windmill turns Codex's enterprise analytics into actionable stats that flow into your existing performance workflow.

## How to connect Codex

**1. Sign in to the OpenAI Admin Console**

Go to the [OpenAI Admin Console](https://admin.openai.com) and sign in with an account that is an **Owner** or **Admin** of your ChatGPT workspace. Select your tenant if asked, then select the ChatGPT workspace.

Being a global admin or an API Platform organization owner doesn't give you access on its own. You need the Owner or Admin role in the ChatGPT workspace itself.

**2. Create an Admin key**

Go to **Credentials > Admin keys** and click **Create new admin key**. Give it a descriptive name, like "Windmill".

**3. Set the key's permissions**

Give the key read access to Codex analytics only:

* **Workspace owners:** choose **Custom**, then set **Codex analytics API** to **Read**.
* **Workspace admins:** set **Codex analytics API** to **Read** under **Permissions**.

This grants the `codex.enterprise.analytics.read` scope. Leave every other permission set to **None**.

**4. Choose an expiration and copy the key**

Pick an expiration, click **Submit**, and copy the secret. OpenAI only shows it once, so keep it somewhere safe until you paste it into Windmill.

**5. Get your Workspace ID**

Go to the [ChatGPT Admin console](https://chatgpt.com/admin) and copy your **Workspace ID**. This identifies which ChatGPT workspace Windmill should pull analytics from. It must be the same workspace you created the Admin key in.

**6. Open the Codex integration in Windmill**

In Windmill, navigate to [Settings > Integrations](https://app.gowindmill.com/COMPANY/config/integrations), find **Codex**, and click **Connect**.

**7. Enter your credentials and connect**

Paste your Admin key and Workspace ID into the input fields and click **Connect**. Windmill will validate the credentials and begin syncing analytics within the hour.

> [!WARNING]
>
> Don't create the key in the API Platform ([platform.openai.com](https://platform.openai.com)). API Platform keys, including API Platform organization Admin keys, can't read ChatGPT workspace data. The key must come from the [OpenAI Admin Console](https://admin.openai.com).

> [!NOTE]
>
> Codex is an account-level integration — an admin connects it once and it covers your entire ChatGPT workspace. Individual users don't need to connect separately.

## Connected data

When connected, Windmill syncs **per-user analytics** from Codex's Enterprise Analytics API. This is usage data — Windmill does not access any code, prompts, conversations, or file content.

All stats are broken down by **client surface** (e.g., Codex in ChatGPT, Codex in an IDE, or other clients) so you can see where your team is using Codex.

| Stat | Description | Unit |
| - | - | - |
| Threads | Number of Codex threads created | threads |
| Turns | Number of Codex turns (messages) within threads | turns |
| Credits | Total Codex credits consumed | credits |
| Input Tokens | Total input tokens (cached + uncached) sent to Codex | tokens |
| Output Tokens | Total output tokens generated by Codex | tokens |
| Total Tokens | Total tokens consumed across input and output | tokens |

All stats are tracked per employee, per day, per client surface.

## Visibility and access

Codex stats in Windmill follow the **manager hierarchy** visibility model:

* **Employees** can see their own Codex stats
* **Managers** can see Codex stats for their direct reports and anyone in their reporting chain
* **Admins** can see Codex stats for everyone in the organization
* **Peers** cannot see each other's Codex stats

This means Codex analytics are treated like other sensitive performance data in Windmill — visible to the people who need it for coaching and evaluation, but not exposed broadly.

## Permissions

Windmill requests **read-only** access to Codex's Enterprise Analytics API.

| Permission | Purpose |
| - | - |
| Read user analytics | To sync usage stats per team member into Windmill |
| **No access to code or files** | Windmill never reads, stores, or accesses any code from Codex |
| **No access to prompts or conversations** | Windmill does not read thread content — only aggregate usage counts |
| Read-only access | Windmill never modifies anything in Codex or your OpenAI account |

## User matching

Windmill matches Codex users to employees using their **email address**. If a Codex user's email matches an employee's email in Windmill, their stats are automatically attributed to that employee.

If you notice stats that aren't being attributed correctly, check that the email addresses in your ChatGPT workspace match the employee emails in Windmill.

## FAQs

> [accordion] Do I need a ChatGPT Enterprise plan?
>
> Yes. Codex's analytics API needs an OpenAI Admin key, and Admin keys are only available for eligible managed ChatGPT workspaces, such as ChatGPT Enterprise, Edu, or Healthcare. The integration won't work with ChatGPT's free, Plus, or Team plans.

> [accordion] Does Windmill access any code, prompts, or conversations?
>
> No. Windmill only reads usage analytics from Codex's API — thread counts, turn counts, credit consumption, and token usage. Windmill never accesses code, files, prompts, or conversation content.

> [accordion] How often does data sync?
>
> Windmill syncs with Codex once per hour. New usage data will appear within an hour of the activity happening in Codex.

> [accordion] Can I see my own Codex stats?
>
> Yes. Every employee can see their own Codex stats in Windmill.

> [accordion] Can my peers see my Codex stats?
>
> No. Peers cannot see each other's Codex usage data. Managers can see stats in their reporting scope. Admins, HR Admins, and Data Analysts can view company-wide analytics.

> [accordion] Does each engineer need to connect Codex individually?
>
> No. Codex is an account-level integration. An admin connects it once using an Admin key and Workspace ID, and it covers your entire ChatGPT workspace.

> [accordion] What are the different client surfaces in the breakdown?
>
> Codex stats are broken down by the client surface where the activity happened — for example, Codex in ChatGPT versus Codex in an IDE integration. This helps you understand where your team is using Codex most.

> [accordion] What happens when an engineer leaves?
>
> Their historical Codex stats remain for context, but Windmill stops attributing new activity once they are an Archived user.

> [accordion] I don't see Admin keys under Credentials
>
> If you only see **ChatGPT Access Tokens** under **Credentials**, your workspace doesn't have Admin keys. Admin keys are only available for eligible managed workspaces, such as ChatGPT Enterprise, Edu, or Healthcare, and availability can vary by plan and rollout. ChatGPT Access Tokens won't work with Windmill.
>
> Also check that you selected the right tenant and workspace, and that you're an Owner or Admin of that workspace.

> [accordion] I don't see Codex analytics API as a permission
>
> The **Codex analytics API** permission only appears when Codex is available in the selected workspace. Check that Codex is turned on for your workspace. If it still doesn't appear, contact OpenAI Support. Don't pick a different permission in its place.

> [accordion] A key that worked has stopped working
>
> In the [OpenAI Admin Console](https://admin.openai.com), go to **Credentials > Admin keys** and check the key's status and expiration. A key stops working if it expires or is revoked.
>
> A key also stops working if the person who created it loses their Owner or Admin role or their account is deactivated. This happens even if the key was set to never expire. Create a new key and reconnect Codex in Windmill.

> [accordion] Why aren't my Codex stats showing up?
>
> This usually happens when your email in your ChatGPT workspace doesn't match your email in Windmill. Make sure the email addresses match, or ask an admin to check the user mapping.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.