feat(api): update usage APIs and documentation

[apcha-oai]

Summary

Updates organization usage filtering, Responses and Chat Completions usage types, and API documentation.

Changes

• Add optional line_items filtering to organization cost usage requests, allowing results to be limited to exact cost line-item names
• Remove the unlaunched compute_units field from Responses and Chat Completions usage types
• Refresh model examples, documentation links, and reasoning-model guidance across affected API documentation

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T22:02:49.346484Z	775bd5c	New commits
🔒 Security Review	✅ Completed 2026-09-01T22:03:15.239135Z	775bd5c	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Castiron custom code

✅ No new custom-code files detected.

53 mixed files remain; 0 existing customizations changed; 10 generated baselines changed.

Compared aced76c09141 → 775bd5cee894. Generated baselines verified.

File	Result	Current custom patch
openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt	Generated baseline changed	+42 / −57
openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt	Generated baseline changed	+58 / −0
openai-java-core/src/test/kotlin/com/openai/models/beta/responses/BetaResponsesServerEventTest.kt	Generated baseline changed	+101 / −0
openai-java-core/src/test/kotlin/com/openai/models/responses/ResponsesServerEventTest.kt	Generated baseline changed	+101 / −0
openai-java-core/src/test/kotlin/com/openai/services/async/ResponseServiceAsyncTest.kt	Generated baseline changed	+3 / −0
openai-java-core/src/test/kotlin/com/openai/services/async/beta/ResponseServiceAsyncTest.kt	Generated baseline changed	+1 / −4
openai-java-core/src/test/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsyncTest.kt	Generated baseline changed	+2 / −0
openai-java-core/src/test/kotlin/com/openai/services/blocking/ResponseServiceTest.kt	Generated baseline changed	+3 / −0
openai-java-core/src/test/kotlin/com/openai/services/blocking/beta/ResponseServiceTest.kt	Generated baseline changed	+1 / −3
openai-java-core/src/test/kotlin/com/openai/services/blocking/chat/ChatCompletionServiceTest.kt	Generated baseline changed	+2 / −0

43 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/finetuning/checkpoints/PermissionServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/BetaServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionServiceImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
• openai-java-core/src/main/kotlin/com/openai/services/blocking/finetuning/checkpoints/PermissionServiceImpl.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/CompletionServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/ImageServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/WebhookServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/beta/ThreadServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/async/beta/threads/RunServiceAsyncTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/CompletionServiceTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/ImageServiceTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/WebhookServiceTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/audio/TranscriptionServiceTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/beta/ThreadServiceTest.kt
• openai-java-core/src/test/kotlin/com/openai/services/blocking/beta/threads/RunServiceTest.kt

3 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 33564085263 --repo openai/openai-java \
  --name castiron-custom-code-33564085263-1 --dir /tmp/castiron-custom-code-33564085263-1
git apply --stat /tmp/castiron-custom-code-33564085263-1/custom-code.patch
cat /tmp/castiron-custom-code-33564085263-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin aced76c091413047b1dedf7c16d2f53f7c5bd196 775bd5cee894d9ae574f3d3ce453eaeaa93f9aa6
python3 scripts/castiron/custom_code_report.py report \
  --base aced76c091413047b1dedf7c16d2f53f7c5bd196 \
  --head 775bd5cee894d9ae574f3d3ce453eaeaa93f9aa6 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-775bd5cee894
cat /tmp/castiron-custom-code-775bd5cee894/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 17.234s for Java SDK PR #961.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	513ms
tests/chat-completions-create.test.ts	✅ Passed	456ms
tests/chat-completions-stream.test.ts	✅ Passed	349ms
tests/files-content-binary.test.ts	✅ Passed	282ms
tests/files-create-multipart.test.ts	✅ Passed	292ms
tests/files-list-pagination.test.ts	✅ Passed	279ms
tests/initialize-config.test.ts	✅ Passed	212ms
tests/instance-isolation.test.ts	✅ Passed	212ms
tests/models-list.test.ts	✅ Passed	178ms
tests/responses-background-lifecycle.test.ts	✅ Passed	275ms
tests/responses-body-method-errors.test.ts	✅ Passed	512ms
tests/responses-cancel-timeout.test.ts	✅ Passed	286ms
tests/responses-cancel.test.ts	✅ Passed	255ms
tests/responses-compact-retries.test.ts	✅ Passed	478ms
tests/responses-compact.test.ts	✅ Passed	422ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	769ms
tests/responses-create-advanced.test.ts	✅ Passed	1.396s
tests/responses-create-disconnect.test.ts	✅ Passed	1.11s
tests/responses-create-errors.test.ts	✅ Passed	423ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	338ms
tests/responses-create-retries.test.ts	✅ Passed	245ms
tests/responses-create-stream-failures.test.ts	✅ Passed	301ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	251ms
tests/responses-create-stream-wire.test.ts	✅ Passed	6.416s
tests/responses-create-stream.test.ts	✅ Passed	147ms
tests/responses-create-terminal-states.test.ts	✅ Passed	490ms
tests/responses-create-timeout.test.ts	✅ Passed	265ms
tests/responses-create.test.ts	✅ Passed	322ms
tests/responses-delete.test.ts	✅ Passed	252ms
tests/responses-input-items-errors.test.ts	✅ Passed	294ms
tests/responses-input-items-list.test.ts	✅ Passed	298ms
tests/responses-input-items-options.test.ts	✅ Passed	276ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	218ms
tests/responses-input-tokens-count.test.ts	✅ Passed	535ms
tests/responses-malformed-inputs.test.ts	✅ Passed	5.281s
tests/responses-not-found-errors.test.ts	✅ Passed	452ms
tests/responses-parse.test.ts	✅ Passed	819ms
tests/responses-retrieve-retries.test.ts	✅ Passed	1.153s
tests/responses-retrieve.test.ts	✅ Passed	431ms
tests/responses-stored-method-errors.test.ts	✅ Passed	1.001s
tests/retry-behavior.test.ts	✅ Passed	3.444s
tests/sdk-error-shape.test.ts	✅ Passed	444ms

View OkTest run #33564050658

_{SDK merge (b1a8112c950c) · head (775bd5cee894) · base (aced76c09141) · OkTest (2b1bdfd25e98)}

[jbeckwith-oai]

Blocking scope issue: the stated outcome is limited to removing the unlaunched compute_units usage fields, but this exact diff also promotes unrelated schema and public-surface changes—for example, a new organization-cost line_items filter, a new max_messages incomplete-reason value, and broad model/example/documentation updates. Those changes are not narrowly necessary for the field removal and make the patch carry behavior/API surface that the PR does not describe. Please regenerate from a baseline/config containing only the compute_units removal, or split and explicitly document/approve the broader promotion. I understand the compatibility/breaking-change checks triggered by the intentional field removal; that expected break is not this finding.

[jbeckwith-oai]

Thanks for broadening the description. One public-surface change is still missing from the stated scope: this diff adds max_messages to the Responses/Beta Responses incomplete-reason enum/type in addition to the usage and documentation changes. That is a generated public API change, not merely a documentation refresh. Please explicitly include it in the description (or remove it) so the reviewed scope matches the exact diff.

[HAYDEN-OAI]

Reviewed the complete diff at 775bd5cee894, including the intentional removal of the unlaunched compute_units field, optional organization-cost line_items filtering, stable/beta max_messages reason support, and schema/documentation updates. Checked usage-model builders/serialization, immutable filter parameters and query encoding, admin authentication, and complete stable/beta reason conversion paths.

No substantive issues found. Static source review only.