> ## 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 a **ChatGPT Enterprise** or **Codex** plan. You must be on one of these plans to connect this integration.
</Warning>

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

<Steps>
  <Step title="Get your API key from OpenAI">
    Go to the [Codex API reference](https://chatgpt.com/codex/cloud/settings/apireference) and follow the **Authentication** instructions to obtain an API key with the proper scopes.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Open the Codex integration in Windmill">
    In Windmill, navigate to [Settings > Integrations](https://app.gowindmill.com/COMPANY/config/integrations), find **Codex**, and click **Connect**.
  </Step>

  <Step title="Enter your credentials and connect">
    Paste your API key and Workspace ID into the input fields and click **Connect**. Windmill will validate the credentials and begin syncing analytics within the hour.
  </Step>
</Steps>

<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.
</Note>

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

<AccordionGroup>
  <Accordion title="Do I need a ChatGPT Enterprise or Codex plan?">
    Yes. Codex's analytics API is only available on the ChatGPT Enterprise or Codex plan. The integration won't work with ChatGPT's free, Plus, or Team plans.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Can I see my own Codex stats?">
    Yes. Every employee can see their own Codex stats in Windmill.
  </Accordion>

  <Accordion title="Can my coworkers see my Codex stats?">
    No. Codex stats follow the manager hierarchy — only your manager (and their managers) can see your stats. Peers cannot see each other's Codex usage data.
  </Accordion>

  <Accordion title="Does each engineer need to connect Codex individually?">
    No. Codex is an account-level integration. An admin connects it once using an API key and Workspace ID, and it covers your entire ChatGPT workspace.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>