diff --git a/en/resources/admin/index.md b/en/resources/admin/index.md index 435bdee5..1d12c4b3 100644 --- a/en/resources/admin/index.md +++ b/en/resources/admin/index.md @@ -2,373 +2,592 @@ # Organization -# Audit Logs - -## List audit logs +# Admin API Keys -**get** `/organization/audit_logs` +## Create admin API key -List user actions and configuration changes within this organization. +**post** `/organization/admin_api_keys` -### Query Parameters +Create an organization admin API key -- `actor_emails: optional array of string` +### Body Parameters - Return only events performed by users with these emails. +- `name: string` -- `actor_ids: optional array of string` +- `expires_in_seconds: optional number` - Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID. + The number of seconds until the API key expires. Omit this field for a key that does not expire. -- `after: optional string` +### Returns - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. +- `value: string` -- `before: optional string` + The value of the API key. Only shown on create. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. +### Example -- `effective_at: optional object { gt, gte, lt, lte }` +```http +curl https://api.openai.com/v1/organization/admin_api_keys \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "name": "New Admin Key", + "expires_in_seconds": 2592000 + }' +``` - Return only events whose `effective_at` (Unix seconds) is in this range. +#### Response - - `gt: optional number` +```json +{ + "id": "key_abc", + "created_at": 1711471533, + "expires_at": 1714063533, + "object": "organization.admin_api_key", + "owner": { + "id": "sa_456", + "created_at": 1711471533, + "name": "My Service Account", + "object": "organization.user", + "role": "owner", + "type": "user" + }, + "redacted_value": "sk-admin...def", + "last_used_at": 1711471534, + "name": "Administration Key", + "value": "sk-admin-1234abcd" +} +``` - Return only events whose `effective_at` (Unix seconds) is greater than this value. +### Example - - `gte: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/admin_api_keys \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "New Admin Key", + "expires_in_seconds": 2592000 + }' +``` - Return only events whose `effective_at` (Unix seconds) is greater than or equal to this value. +#### Response - - `lt: optional number` +```json +{ + "object": "organization.admin_api_key", + "id": "key_xyz", + "name": "New Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "expires_at": 1714063533, + "last_used_at": 1711471534, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + }, + "value": "sk-admin-1234abcd" +} +``` - Return only events whose `effective_at` (Unix seconds) is less than this value. +## Delete admin API key - - `lte: optional number` +**delete** `/organization/admin_api_keys/{key_id}` - Return only events whose `effective_at` (Unix seconds) is less than or equal to this value. +Delete an organization admin API key -- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` +### Path Parameters - Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](/docs/api-reference/audit-logs/object). +- `key_id: string` - - `"api_key.created"` + The ID of the API key to be deleted. - - `"api_key.updated"` +### Returns - - `"api_key.deleted"` +- `id: string` - - `"certificate.created"` +- `deleted: boolean` - - `"certificate.updated"` +- `object: "organization.admin_api_key.deleted"` - - `"certificate.deleted"` + - `"organization.admin_api_key.deleted"` - - `"certificates.activated"` +### Example - - `"certificates.deactivated"` +```http +curl https://api.openai.com/v1/organization/admin_api_keys/$KEY_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"checkpoint.permission.created"` +#### Response - - `"checkpoint.permission.deleted"` +```json +{ + "id": "key_abc", + "deleted": true, + "object": "organization.admin_api_key.deleted" +} +``` - - `"external_key.registered"` +### Example - - `"external_key.removed"` +```http +curl -X DELETE https://api.openai.com/v1/organization/admin_api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"group.created"` +#### Response - - `"group.updated"` +```json +{ + "id": "key_abc", + "object": "organization.admin_api_key.deleted", + "deleted": true +} +``` - - `"group.deleted"` +## List all organization and project API keys. - - `"invite.sent"` +**get** `/organization/admin_api_keys` - - `"invite.accepted"` +List organization API keys - - `"invite.deleted"` +### Query Parameters - - `"ip_allowlist.created"` +- `after: optional string` - - `"ip_allowlist.updated"` + Return keys with IDs that come after this ID in the pagination order. - - `"ip_allowlist.deleted"` +- `limit: optional number` - - `"ip_allowlist.config.activated"` + Maximum number of keys to return. - - `"ip_allowlist.config.deactivated"` +- `order: optional "asc" or "desc"` - - `"login.succeeded"` + Order results by creation time, ascending or descending. - - `"login.failed"` + - `"asc"` - - `"logout.succeeded"` + - `"desc"` - - `"logout.failed"` +### Returns - - `"organization.updated"` +- `data: array of AdminAPIKey` - - `"project.created"` + - `id: string` - - `"project.updated"` + The identifier, which can be referenced in API endpoints - - `"project.archived"` + - `created_at: number` - - `"project.deleted"` + The Unix timestamp (in seconds) of when the API key was created - - `"rate_limit.updated"` + - `expires_at: number` - - `"rate_limit.deleted"` + The Unix timestamp (in seconds) of when the API key expires - - `"resource.deleted"` + - `object: "organization.admin_api_key"` - - `"tunnel.created"` + The object type, which is always `organization.admin_api_key` - - `"tunnel.updated"` + - `"organization.admin_api_key"` - - `"tunnel.deleted"` + - `owner: object { id, created_at, name, 3 more }` - - `"workload_identity_provider.created"` + - `id: optional string` - - `"workload_identity_provider.updated"` + The identifier, which can be referenced in API endpoints - - `"workload_identity_provider.deleted"` + - `created_at: optional number` - - `"workload_identity_provider_mapping.created"` + The Unix timestamp (in seconds) of when the user was created - - `"workload_identity_provider_mapping.updated"` + - `name: optional string` - - `"workload_identity_provider_mapping.deleted"` + The name of the user - - `"role.created"` + - `object: optional string` - - `"role.updated"` + The object type, which is always organization.user - - `"role.deleted"` + - `role: optional string` - - `"role.assignment.created"` + Always `owner` - - `"role.assignment.deleted"` + - `type: optional string` - - `"role.bound_to_resource"` + Always `user` - - `"role.unbound_from_resource"` + - `redacted_value: string` - - `"scim.enabled"` + The redacted value of the API key - - `"scim.disabled"` + - `last_used_at: optional number` - - `"service_account.created"` + The Unix timestamp (in seconds) of when the API key was last used - - `"service_account.updated"` + - `name: optional string` - - `"service_account.deleted"` + The name of the API key - - `"user.added"` +- `has_more: boolean` - - `"user.updated"` +- `object: "list"` - - `"user.deleted"` + - `"list"` - - `"tenant.metadata.updated"` +- `first_id: optional string` - - `"tenant.microsoft_entra_mapping.upserted"` +- `last_id: optional string` - - `"tenant.microsoft_entra_mapping.deleted"` +### Example - - `"tenant.workload_identity.provider.created"` +```http +curl https://api.openai.com/v1/organization/admin_api_keys \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"tenant.workload_identity.provider.updated"` +#### Response - - `"tenant.workload_identity.provider.archived"` +```json +{ + "data": [ + { + "id": "key_abc", + "created_at": 1711471533, + "expires_at": 1714063533, + "object": "organization.admin_api_key", + "owner": { + "id": "sa_456", + "created_at": 1711471533, + "name": "My Service Account", + "object": "organization.user", + "role": "owner", + "type": "user" + }, + "redacted_value": "sk-admin...def", + "last_used_at": 1711471534, + "name": "Administration Key" + } + ], + "has_more": false, + "object": "list", + "first_id": "key_abc", + "last_id": "key_xyz" +} +``` - - `"tenant.workload_identity.mapping.created"` +### Example - - `"tenant.workload_identity.mapping.updated"` +```http +curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"tenant.workload_identity.mapping.archived"` +#### Response - - `"tenant.workload_identity.binding.created"` +```json +{ + "object": "list", + "data": [ + { + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...def", + "created_at": 1711471533, + "expires_at": 1714063533, + "last_used_at": 1711471534, + "owner": { + "type": "service_account", + "object": "organization.service_account", + "id": "sa_456", + "name": "My Service Account", + "created_at": 1711471533, + "role": "member" + } + } + ], + "first_id": "key_abc", + "last_id": "key_abc", + "has_more": false +} +``` - - `"tenant.workload_identity.principal.provisioned"` +## Retrieve admin API key - - `"tenant.admin_api_key.created"` +**get** `/organization/admin_api_keys/{key_id}` - - `"tenant.admin_api_key.updated"` +Retrieve a single organization API key - - `"tenant.admin_api_key.deleted"` +### Path Parameters - - `"tenant.project_api_key.created"` +- `key_id: string` - - `"tenant.chatgpt_access_token.revoked"` + The ID of the API key. - - `"tenant.migration.completed"` +### Returns - - `"tenant.sso.migrated"` +- `AdminAPIKey object { id, created_at, expires_at, 5 more }` - - `"tenant.domains.migrated"` + Represents an individual Admin API key in an org. - - `"tenant.sso_connection.created"` + - `id: string` - - `"tenant.sso_connection.updated"` + The identifier, which can be referenced in API endpoints - - `"tenant.sso_connection.deleted"` + - `created_at: number` - - `"tenant.sso_connection.setup.started"` + The Unix timestamp (in seconds) of when the API key was created - - `"tenant.policy.created"` + - `expires_at: number` - - `"tenant.policy.updated"` + The Unix timestamp (in seconds) of when the API key expires - - `"tenant.policy.deleted"` + - `object: "organization.admin_api_key"` - - `"tenant.policy.attached"` + The object type, which is always `organization.admin_api_key` - - `"tenant.policy.detached"` + - `"organization.admin_api_key"` - - `"tenant.principal_authentication_policy.resolved"` + - `owner: object { id, created_at, name, 3 more }` - - `"tenant.scim.setup.started"` + - `id: optional string` - - `"tenant.scim.deletion.requested"` + The identifier, which can be referenced in API endpoints - - `"tenant.scim.directory.created"` + - `created_at: optional number` - - `"tenant.product_access_policy.updated"` + The Unix timestamp (in seconds) of when the user was created - - `"tenant.resource_share_grant.created"` + - `name: optional string` - - `"tenant.resource_share_grant.updated"` + The name of the user - - `"tenant.resource_share_grant.accepted"` + - `object: optional string` - - `"tenant.resource_share_grant.declined"` + The object type, which is always organization.user - - `"tenant.resource_share_grant.revoked"` + - `role: optional string` - - `"tenant.resource_share_grant.deleted"` + Always `owner` - - `"tenant.service_account.updated"` + - `type: optional string` - - `"tenant.service_account.deleted"` + Always `user` - - `"tenant.service_account.token.revoked"` + - `redacted_value: string` - - `"tenant.billing.overage_limit.updated"` + The redacted value of the API key - - `"tenant.billing.alerts.updated"` + - `last_used_at: optional number` - - `"tenant.billing.info.updated"` + The Unix timestamp (in seconds) of when the API key was last used - - `"tenant.usage_limit.workspace.updated"` + - `name: optional string` - - `"tenant.usage_limit.group.updated"` + The name of the API key - - `"tenant.usage_limit.user.updated"` +### Example - - `"tenant.usage_limit.increase_request.updated"` +```http +curl https://api.openai.com/v1/organization/admin_api_keys/$KEY_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"tenant.usage_limit.increase_request.resolved"` +#### Response - - `"tenant.group.created"` +```json +{ + "id": "key_abc", + "created_at": 1711471533, + "expires_at": 1714063533, + "object": "organization.admin_api_key", + "owner": { + "id": "sa_456", + "created_at": 1711471533, + "name": "My Service Account", + "object": "organization.user", + "role": "owner", + "type": "user" + }, + "redacted_value": "sk-admin...def", + "last_used_at": 1711471534, + "name": "Administration Key" +} +``` - - `"tenant.group.updated"` +### Example - - `"tenant.group.deleted"` +```http +curl https://api.openai.com/v1/organization/admin_api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"tenant.group.member.added"` +#### Response - - `"tenant.group.member.removed"` +```json +{ + "object": "organization.admin_api_key", + "id": "key_abc", + "name": "Main Admin Key", + "redacted_value": "sk-admin...xyz", + "created_at": 1711471533, + "last_used_at": 1711471534, + "owner": { + "type": "user", + "object": "organization.user", + "id": "user_123", + "name": "John Doe", + "created_at": 1711471533, + "role": "owner" + } +} +``` - - `"tenant.migration_rollout.status.updated"` +## Domain Types - - `"tenant.migration_rollout.tier.updated"` +### Admin API Key - - `"tenant.role.metadata.updated"` +- `AdminAPIKey object { id, created_at, expires_at, 5 more }` - - `"tenant.custom_role.created"` + Represents an individual Admin API key in an org. - - `"tenant.custom_role.updated"` + - `id: string` - - `"tenant.custom_role.deleted"` + The identifier, which can be referenced in API endpoints - - `"tenant.role_assignment.created"` + - `created_at: number` - - `"tenant.role_assignment.deleted"` + The Unix timestamp (in seconds) of when the API key was created - - `"tenant.resource_role_assignment.created"` + - `expires_at: number` - - `"tenant.resource_role_assignment.deleted"` + The Unix timestamp (in seconds) of when the API key expires - - `"tenant.resource_access.updated"` + - `object: "organization.admin_api_key"` - - `"tenant.resource_access.deleted"` + The object type, which is always `organization.admin_api_key` - - `"tenant.session_policy.created"` + - `"organization.admin_api_key"` - - `"tenant.session_policy.updated"` + - `owner: object { id, created_at, name, 3 more }` - - `"tenant.session_policy.deleted"` + - `id: optional string` - - `"tenant.session_revocation.started"` + The identifier, which can be referenced in API endpoints - - `"tenant.third_party_app_policy.updated"` + - `created_at: optional number` - - `"tenant.user.added"` + The Unix timestamp (in seconds) of when the user was created - - `"tenant.user.updated"` + - `name: optional string` - - `"tenant.user.removed"` + The name of the user - - `"tenant.user.looked_up"` + - `object: optional string` - - `"tenant.user.invited"` + The object type, which is always organization.user - - `"tenant.membership.revoked"` + - `role: optional string` - - `"tenant.api_organization_invite.upserted"` + Always `owner` - - `"tenant.api_organization_invite.deleted"` + - `type: optional string` - - `"tenant.chatgpt_workspace_invite.upserted"` + Always `user` - - `"tenant.membership.accepted"` + - `redacted_value: string` - - `"tenant.membership.declined"` + The redacted value of the API key - - `"tenant.workspace_invite_email_settings.updated"` + - `last_used_at: optional number` -- `limit: optional number` + The Unix timestamp (in seconds) of when the API key was last used - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `name: optional string` -- `project_ids: optional array of string` + The name of the API key - Return only events for these projects. +### Admin API Key Create Response -- `resource_ids: optional array of string` +- `AdminAPIKeyCreateResponse = AdminAPIKey` - Return only events performed on these targets. For example, a project ID updated. For ChatGPT connector role events, use the workspace connector resource ID shown in `details.id`, such as `__`. + Represents an individual Admin API key in an org. -- `tenant_only: optional boolean` + - `value: string` - Return only tenant-scoped events associated with this organization. Required for tenant-scoped events such as `role.bound_to_resource` and `role.unbound_from_resource`. When `true`, all supplied event types must be tenant-scoped. + The value of the API key. Only shown on create. -### Returns +### Admin API Key Delete Response -- `data: array of object { id, effective_at, type, 57 more }` +- `AdminAPIKeyDeleteResponse object { id, deleted, object }` - `id: string` - The ID of this log. + - `deleted: boolean` - - `effective_at: number` + - `object: "organization.admin_api_key.deleted"` - The Unix timestamp (in seconds) of the event. + - `"organization.admin_api_key.deleted"` - - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` +# Audit Logs - The event type. +## List audit logs + +**get** `/organization/audit_logs` + +List user actions and configuration changes within this organization. + +### Query Parameters + +- `actor_emails: optional array of string` + + Return only events performed by users with these emails. + +- `actor_ids: optional array of string` + + Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID. + +- `after: optional string` + + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + +- `before: optional string` + + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + +- `effective_at: optional object { gt, gte, lt, lte }` + + Return only events whose `effective_at` (Unix seconds) is in this range. + + - `gt: optional number` + + Return only events whose `effective_at` (Unix seconds) is greater than this value. + + - `gte: optional number` + + Return only events whose `effective_at` (Unix seconds) is greater than or equal to this value. + + - `lt: optional number` + + Return only events whose `effective_at` (Unix seconds) is less than this value. + + - `lte: optional number` + + Return only events whose `effective_at` (Unix seconds) is less than or equal to this value. + +- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` + + Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](/docs/api-reference/audit-logs/object). - `"api_key.created"` @@ -656,3721 +875,3534 @@ List user actions and configuration changes within this organization. - `"tenant.workspace_invite_email_settings.updated"` - - `actor: optional object { api_key, session, type }` +- `limit: optional number` - The actor who performed the audit logged action. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `api_key: optional object { id, service_account, type, user }` +- `project_ids: optional array of string` - The API Key used to perform the audit logged action. + Return only events for these projects. - - `id: optional string` +- `resource_ids: optional array of string` - The tracking id of the API key. + Return only events performed on these targets. For example, a project ID updated. For ChatGPT connector role events, use the workspace connector resource ID shown in `details.id`, such as `__`. - - `service_account: optional object { id }` +- `tenant_only: optional boolean` - The service account that performed the audit logged action. + Return only tenant-scoped events associated with this organization. Required for tenant-scoped events such as `role.bound_to_resource` and `role.unbound_from_resource`. When `true`, all supplied event types must be tenant-scoped. - - `id: optional string` +### Returns - The service account id. +- `data: array of object { id, effective_at, type, 57 more }` - - `type: optional "user" or "service_account"` + - `id: string` - The type of API key. Can be either `user` or `service_account`. + The ID of this log. - - `"user"` + - `effective_at: number` - - `"service_account"` + The Unix timestamp (in seconds) of the event. - - `user: optional object { id, email }` + - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` - The user who performed the audit logged action. + The event type. - - `id: optional string` + - `"api_key.created"` - The user id. + - `"api_key.updated"` - - `email: optional string` + - `"api_key.deleted"` - The user email. + - `"certificate.created"` - - `session: optional object { ip_address, user }` + - `"certificate.updated"` - The session in which the audit logged action was performed. + - `"certificate.deleted"` - - `ip_address: optional string` + - `"certificates.activated"` - The IP address from which the action was performed. + - `"certificates.deactivated"` - - `user: optional object { id, email }` + - `"checkpoint.permission.created"` - The user who performed the audit logged action. + - `"checkpoint.permission.deleted"` - - `id: optional string` + - `"external_key.registered"` - The user id. + - `"external_key.removed"` - - `email: optional string` + - `"group.created"` - The user email. + - `"group.updated"` - - `type: optional "session" or "api_key"` + - `"group.deleted"` - The type of actor. Is either `session` or `api_key`. + - `"invite.sent"` - - `"session"` + - `"invite.accepted"` - - `"api_key"` + - `"invite.deleted"` - - `"api_key.created": optional object { id, data }` + - `"ip_allowlist.created"` - The details for events with this `type`. + - `"ip_allowlist.updated"` - - `id: optional string` + - `"ip_allowlist.deleted"` - The tracking ID of the API key. + - `"ip_allowlist.config.activated"` - - `data: optional object { scopes }` + - `"ip_allowlist.config.deactivated"` - The payload used to create the API key. + - `"login.succeeded"` - - `scopes: optional array of string` + - `"login.failed"` - A list of scopes allowed for the API key, e.g. `["api.model.request"]` + - `"logout.succeeded"` - - `"api_key.deleted": optional object { id }` + - `"logout.failed"` - The details for events with this `type`. + - `"organization.updated"` - - `id: optional string` + - `"project.created"` - The tracking ID of the API key. + - `"project.updated"` - - `"api_key.updated": optional object { id, changes_requested }` + - `"project.archived"` - The details for events with this `type`. + - `"project.deleted"` - - `id: optional string` + - `"rate_limit.updated"` - The tracking ID of the API key. + - `"rate_limit.deleted"` - - `changes_requested: optional object { scopes }` + - `"resource.deleted"` - The payload used to update the API key. + - `"tunnel.created"` - - `scopes: optional array of string` + - `"tunnel.updated"` - A list of scopes allowed for the API key, e.g. `["api.model.request"]` + - `"tunnel.deleted"` - - `"certificate.created": optional object { id, name }` + - `"workload_identity_provider.created"` - The details for events with this `type`. + - `"workload_identity_provider.updated"` - - `id: optional string` + - `"workload_identity_provider.deleted"` - The certificate ID. + - `"workload_identity_provider_mapping.created"` - - `name: optional string` + - `"workload_identity_provider_mapping.updated"` - The name of the certificate. + - `"workload_identity_provider_mapping.deleted"` - - `"certificate.deleted": optional object { id, certificate, name }` + - `"role.created"` - The details for events with this `type`. + - `"role.updated"` - - `id: optional string` + - `"role.deleted"` - The certificate ID. + - `"role.assignment.created"` - - `certificate: optional string` + - `"role.assignment.deleted"` - The certificate content in PEM format. + - `"role.bound_to_resource"` - - `name: optional string` + - `"role.unbound_from_resource"` - The name of the certificate. + - `"scim.enabled"` - - `"certificate.updated": optional object { id, name }` + - `"scim.disabled"` - The details for events with this `type`. + - `"service_account.created"` - - `id: optional string` + - `"service_account.updated"` - The certificate ID. + - `"service_account.deleted"` - - `name: optional string` + - `"user.added"` - The name of the certificate. + - `"user.updated"` - - `"certificates.activated": optional object { certificates }` + - `"user.deleted"` - The details for events with this `type`. + - `"tenant.metadata.updated"` - - `certificates: optional array of object { id, name }` + - `"tenant.microsoft_entra_mapping.upserted"` - - `id: optional string` + - `"tenant.microsoft_entra_mapping.deleted"` - The certificate ID. + - `"tenant.workload_identity.provider.created"` - - `name: optional string` + - `"tenant.workload_identity.provider.updated"` - The name of the certificate. + - `"tenant.workload_identity.provider.archived"` - - `"certificates.deactivated": optional object { certificates }` + - `"tenant.workload_identity.mapping.created"` - The details for events with this `type`. + - `"tenant.workload_identity.mapping.updated"` - - `certificates: optional array of object { id, name }` + - `"tenant.workload_identity.mapping.archived"` - - `id: optional string` + - `"tenant.workload_identity.binding.created"` - The certificate ID. + - `"tenant.workload_identity.principal.provisioned"` - - `name: optional string` + - `"tenant.admin_api_key.created"` - The name of the certificate. + - `"tenant.admin_api_key.updated"` - - `"checkpoint.permission.created": optional object { id, data }` + - `"tenant.admin_api_key.deleted"` - The project and fine-tuned model checkpoint that the checkpoint permission was created for. + - `"tenant.project_api_key.created"` - - `id: optional string` - - The ID of the checkpoint permission. + - `"tenant.chatgpt_access_token.revoked"` - - `data: optional object { fine_tuned_model_checkpoint, project_id }` + - `"tenant.migration.completed"` - The payload used to create the checkpoint permission. + - `"tenant.sso.migrated"` - - `fine_tuned_model_checkpoint: optional string` + - `"tenant.domains.migrated"` - The ID of the fine-tuned model checkpoint. + - `"tenant.sso_connection.created"` - - `project_id: optional string` + - `"tenant.sso_connection.updated"` - The ID of the project that the checkpoint permission was created for. + - `"tenant.sso_connection.deleted"` - - `"checkpoint.permission.deleted": optional object { id }` + - `"tenant.sso_connection.setup.started"` - The details for events with this `type`. + - `"tenant.policy.created"` - - `id: optional string` + - `"tenant.policy.updated"` - The ID of the checkpoint permission. + - `"tenant.policy.deleted"` - - `"external_key.registered": optional object { id, data }` + - `"tenant.policy.attached"` - The details for events with this `type`. + - `"tenant.policy.detached"` - - `id: optional string` + - `"tenant.principal_authentication_policy.resolved"` - The ID of the external key configuration. + - `"tenant.scim.setup.started"` - - `data: optional unknown` + - `"tenant.scim.deletion.requested"` - The configuration for the external key. + - `"tenant.scim.directory.created"` - - `"external_key.removed": optional object { id }` + - `"tenant.product_access_policy.updated"` - The details for events with this `type`. + - `"tenant.resource_share_grant.created"` - - `id: optional string` + - `"tenant.resource_share_grant.updated"` - The ID of the external key configuration. + - `"tenant.resource_share_grant.accepted"` - - `"group.created": optional object { id, data }` + - `"tenant.resource_share_grant.declined"` - The details for events with this `type`. + - `"tenant.resource_share_grant.revoked"` - - `id: optional string` + - `"tenant.resource_share_grant.deleted"` - The ID of the group. + - `"tenant.service_account.updated"` - - `data: optional object { group_name }` + - `"tenant.service_account.deleted"` - Information about the created group. + - `"tenant.service_account.token.revoked"` - - `group_name: optional string` + - `"tenant.billing.overage_limit.updated"` - The group name. + - `"tenant.billing.alerts.updated"` - - `"group.deleted": optional object { id }` + - `"tenant.billing.info.updated"` - The details for events with this `type`. + - `"tenant.usage_limit.workspace.updated"` - - `id: optional string` + - `"tenant.usage_limit.group.updated"` - The ID of the group. + - `"tenant.usage_limit.user.updated"` - - `"group.updated": optional object { id, changes_requested }` + - `"tenant.usage_limit.increase_request.updated"` - The details for events with this `type`. + - `"tenant.usage_limit.increase_request.resolved"` - - `id: optional string` + - `"tenant.group.created"` - The ID of the group. + - `"tenant.group.updated"` - - `changes_requested: optional object { group_name }` + - `"tenant.group.deleted"` - The payload used to update the group. + - `"tenant.group.member.added"` - - `group_name: optional string` + - `"tenant.group.member.removed"` - The updated group name. + - `"tenant.migration_rollout.status.updated"` - - `"invite.accepted": optional object { id }` + - `"tenant.migration_rollout.tier.updated"` - The details for events with this `type`. + - `"tenant.role.metadata.updated"` - - `id: optional string` + - `"tenant.custom_role.created"` - The ID of the invite. + - `"tenant.custom_role.updated"` - - `"invite.deleted": optional object { id }` + - `"tenant.custom_role.deleted"` - The details for events with this `type`. + - `"tenant.role_assignment.created"` - - `id: optional string` + - `"tenant.role_assignment.deleted"` - The ID of the invite. + - `"tenant.resource_role_assignment.created"` - - `"invite.sent": optional object { id, data }` + - `"tenant.resource_role_assignment.deleted"` - The details for events with this `type`. + - `"tenant.resource_access.updated"` - - `id: optional string` + - `"tenant.resource_access.deleted"` - The ID of the invite. + - `"tenant.session_policy.created"` - - `data: optional object { email, role }` + - `"tenant.session_policy.updated"` - The payload used to create the invite. + - `"tenant.session_policy.deleted"` - - `email: optional string` + - `"tenant.session_revocation.started"` - The email invited to the organization. + - `"tenant.third_party_app_policy.updated"` - - `role: optional string` + - `"tenant.user.added"` - The role the email was invited to be. Is either `owner` or `member`. + - `"tenant.user.updated"` - - `"ip_allowlist.config.activated": optional object { configs }` + - `"tenant.user.removed"` - The details for events with this `type`. + - `"tenant.user.looked_up"` - - `configs: optional array of object { id, name }` + - `"tenant.user.invited"` - The configurations that were activated. + - `"tenant.membership.revoked"` - - `id: optional string` + - `"tenant.api_organization_invite.upserted"` - The ID of the IP allowlist configuration. + - `"tenant.api_organization_invite.deleted"` - - `name: optional string` + - `"tenant.chatgpt_workspace_invite.upserted"` - The name of the IP allowlist configuration. + - `"tenant.membership.accepted"` - - `"ip_allowlist.config.deactivated": optional object { configs }` + - `"tenant.membership.declined"` - The details for events with this `type`. + - `"tenant.workspace_invite_email_settings.updated"` - - `configs: optional array of object { id, name }` + - `actor: optional object { api_key, session, type }` - The configurations that were deactivated. + The actor who performed the audit logged action. - - `id: optional string` + - `api_key: optional object { id, service_account, type, user }` - The ID of the IP allowlist configuration. + The API Key used to perform the audit logged action. - - `name: optional string` + - `id: optional string` - The name of the IP allowlist configuration. + The tracking id of the API key. - - `"ip_allowlist.created": optional object { id, allowed_ips, name }` + - `service_account: optional object { id }` - The details for events with this `type`. + The service account that performed the audit logged action. - `id: optional string` - The ID of the IP allowlist configuration. + The service account id. - - `allowed_ips: optional array of string` + - `type: optional "user" or "service_account"` - The IP addresses or CIDR ranges included in the configuration. + The type of API key. Can be either `user` or `service_account`. - - `name: optional string` + - `"user"` - The name of the IP allowlist configuration. + - `"service_account"` - - `"ip_allowlist.deleted": optional object { id, allowed_ips, name }` + - `user: optional object { id, email }` - The details for events with this `type`. + The user who performed the audit logged action. - `id: optional string` - The ID of the IP allowlist configuration. + The user id. - - `allowed_ips: optional array of string` + - `email: optional string` - The IP addresses or CIDR ranges that were in the configuration. + The user email. - - `name: optional string` + - `session: optional object { ip_address, user }` - The name of the IP allowlist configuration. + The session in which the audit logged action was performed. - - `"ip_allowlist.updated": optional object { id, allowed_ips }` + - `ip_address: optional string` - The details for events with this `type`. + The IP address from which the action was performed. + + - `user: optional object { id, email }` + + The user who performed the audit logged action. - `id: optional string` - The ID of the IP allowlist configuration. + The user id. - - `allowed_ips: optional array of string` + - `email: optional string` - The updated set of IP addresses or CIDR ranges in the configuration. + The user email. - - `"login.failed": optional object { error_code, error_message }` + - `type: optional "session" or "api_key"` - The details for events with this `type`. + The type of actor. Is either `session` or `api_key`. - - `error_code: optional string` + - `"session"` - The error code of the failure. + - `"api_key"` - - `error_message: optional string` + - `"api_key.created": optional object { id, data }` - The error message of the failure. + The details for events with this `type`. - - `"login.succeeded": optional unknown` + - `id: optional string` - This event has no additional fields beyond the standard audit log attributes. + The tracking ID of the API key. - - `"logout.failed": optional object { error_code, error_message }` + - `data: optional object { scopes }` - The details for events with this `type`. + The payload used to create the API key. - - `error_code: optional string` + - `scopes: optional array of string` - The error code of the failure. + A list of scopes allowed for the API key, e.g. `["api.model.request"]` - - `error_message: optional string` + - `"api_key.deleted": optional object { id }` - The error message of the failure. + The details for events with this `type`. - - `"logout.succeeded": optional unknown` + - `id: optional string` - This event has no additional fields beyond the standard audit log attributes. + The tracking ID of the API key. - - `"organization.updated": optional object { id, changes_requested }` + - `"api_key.updated": optional object { id, changes_requested }` The details for events with this `type`. - `id: optional string` - The organization ID. + The tracking ID of the API key. - - `changes_requested: optional object { api_call_logging, api_call_logging_project_ids, description, 4 more }` + - `changes_requested: optional object { scopes }` - The payload used to update the organization settings. + The payload used to update the API key. - - `api_call_logging: optional string` + - `scopes: optional array of string` - How your organization logs data from supported API calls. One of `disabled`, `enabled_per_call`, `enabled_for_all_projects`, or `enabled_for_selected_projects` + A list of scopes allowed for the API key, e.g. `["api.model.request"]` - - `api_call_logging_project_ids: optional string` + - `"certificate.created": optional object { id, name }` - The list of project ids if api_call_logging is set to `enabled_for_selected_projects` + The details for events with this `type`. - - `description: optional string` + - `id: optional string` - The organization description. + The certificate ID. - `name: optional string` - The organization name. + The name of the certificate. - - `threads_ui_visibility: optional string` + - `"certificate.deleted": optional object { id, certificate, name }` - Visibility of the threads page which shows messages created with the Assistants API and Playground. One of `ANY_ROLE`, `OWNERS`, or `NONE`. + The details for events with this `type`. - - `title: optional string` + - `id: optional string` - The organization title. + The certificate ID. - - `usage_dashboard_visibility: optional string` + - `certificate: optional string` - Visibility of the usage dashboard which shows activity and costs for your organization. One of `ANY_ROLE` or `OWNERS`. + The certificate content in PEM format. - - `project: optional object { id, name }` + - `name: optional string` - The project that the action was scoped to. Absent for actions not scoped to projects. Note that any admin actions taken via Admin API keys are associated with the default project. + The name of the certificate. + + - `"certificate.updated": optional object { id, name }` + + The details for events with this `type`. - `id: optional string` - The project ID. + The certificate ID. - `name: optional string` - The project title. + The name of the certificate. - - `"project.archived": optional object { id }` + - `"certificates.activated": optional object { certificates }` The details for events with this `type`. - - `id: optional string` + - `certificates: optional array of object { id, name }` - The project ID. + - `id: optional string` - - `"project.created": optional object { id, data }` + The certificate ID. - The details for events with this `type`. + - `name: optional string` - - `id: optional string` + The name of the certificate. - The project ID. + - `"certificates.deactivated": optional object { certificates }` - - `data: optional object { name, title }` + The details for events with this `type`. - The payload used to create the project. + - `certificates: optional array of object { id, name }` - - `name: optional string` + - `id: optional string` - The project name. + The certificate ID. - - `title: optional string` + - `name: optional string` - The title of the project as seen on the dashboard. + The name of the certificate. - - `"project.deleted": optional object { id }` + - `"checkpoint.permission.created": optional object { id, data }` - The details for events with this `type`. + The project and fine-tuned model checkpoint that the checkpoint permission was created for. - `id: optional string` - The project ID. - - - `"project.updated": optional object { id, changes_requested }` - - The details for events with this `type`. + The ID of the checkpoint permission. - - `id: optional string` + - `data: optional object { fine_tuned_model_checkpoint, project_id }` - The project ID. + The payload used to create the checkpoint permission. - - `changes_requested: optional object { title }` + - `fine_tuned_model_checkpoint: optional string` - The payload used to update the project. + The ID of the fine-tuned model checkpoint. - - `title: optional string` + - `project_id: optional string` - The title of the project as seen on the dashboard. + The ID of the project that the checkpoint permission was created for. - - `"rate_limit.deleted": optional object { id }` + - `"checkpoint.permission.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The rate limit ID + The ID of the checkpoint permission. - - `"rate_limit.updated": optional object { id, changes_requested }` + - `"external_key.registered": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The rate limit ID + The ID of the external key configuration. - - `changes_requested: optional object { batch_1_day_max_input_tokens, max_audio_megabytes_per_1_minute, max_images_per_1_minute, 3 more }` + - `data: optional unknown` - The payload used to update the rate limits. + The configuration for the external key. - - `batch_1_day_max_input_tokens: optional number` + - `"external_key.removed": optional object { id }` - The maximum batch input tokens per day. Only relevant for certain models. + The details for events with this `type`. - - `max_audio_megabytes_per_1_minute: optional number` + - `id: optional string` - The maximum audio megabytes per minute. Only relevant for certain models. + The ID of the external key configuration. - - `max_images_per_1_minute: optional number` + - `"group.created": optional object { id, data }` - The maximum images per minute. Only relevant for certain models. + The details for events with this `type`. - - `max_requests_per_1_day: optional number` + - `id: optional string` - The maximum requests per day. Only relevant for certain models. + The ID of the group. - - `max_requests_per_1_minute: optional number` + - `data: optional object { group_name }` - The maximum requests per minute. + Information about the created group. - - `max_tokens_per_1_minute: optional number` + - `group_name: optional string` - The maximum tokens per minute. + The group name. - - `"role.assignment.created": optional object { id, principal_id, principal_type, 2 more }` + - `"group.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The identifier of the role assignment. + The ID of the group. - - `principal_id: optional string` + - `"group.updated": optional object { id, changes_requested }` - The principal (user or group) that received the role. + The details for events with this `type`. - - `principal_type: optional string` + - `id: optional string` - The type of principal (user or group) that received the role. + The ID of the group. - - `resource_id: optional string` + - `changes_requested: optional object { group_name }` - The resource the role assignment is scoped to. + The payload used to update the group. - - `resource_type: optional string` + - `group_name: optional string` - The type of resource the role assignment is scoped to. + The updated group name. - - `"role.assignment.deleted": optional object { id, principal_id, principal_type, 2 more }` + - `"invite.accepted": optional object { id }` The details for events with this `type`. - `id: optional string` - The identifier of the role assignment. - - - `principal_id: optional string` - - The principal (user or group) that had the role removed. - - - `principal_type: optional string` - - The type of principal (user or group) that had the role removed. + The ID of the invite. - - `resource_id: optional string` + - `"invite.deleted": optional object { id }` - The resource the role assignment was scoped to. + The details for events with this `type`. - - `resource_type: optional string` + - `id: optional string` - The type of resource the role assignment was scoped to. + The ID of the invite. - - `"role.bound_to_resource": optional object { id, connector_id, connector_name, 7 more }` + - `"invite.sent": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The ID of the resource the role was bound to. ChatGPT workspace connector resources use `__`. - - - `connector_id: optional string` + The ID of the invite. - The connector ID for a ChatGPT workspace connector resource. + - `data: optional object { email, role }` - - `connector_name: optional string` + The payload used to create the invite. - The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. + - `email: optional string` - - `enabled: optional boolean` + The email invited to the organization. - Whether the connector is enabled for the role. + - `role: optional string` - - `permissions: optional array of string` + The role the email was invited to be. Is either `owner` or `member`. - The permissions granted to the role for the resource. + - `"ip_allowlist.config.activated": optional object { configs }` - - `resource_id: optional string` + The details for events with this `type`. - The ID of the resource the role was bound to. + - `configs: optional array of object { id, name }` - - `resource_type: optional string` + The configurations that were activated. - The type of resource the role was bound to. + - `id: optional string` - - `role_id: optional string` + The ID of the IP allowlist configuration. - The ID of the role that was bound to the resource. + - `name: optional string` - - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` + The name of the IP allowlist configuration. - The connector role mutation path that produced the event. + - `"ip_allowlist.config.deactivated": optional object { configs }` - - `"role_toggle"` + The details for events with this `type`. - - `"role_connector_update"` + - `configs: optional array of object { id, name }` - - `"role_delete"` + The configurations that were deactivated. - - `"workspace_permissions"` + - `id: optional string` - - `"connector_publish"` + The ID of the IP allowlist configuration. - - `workspace_id: optional string` + - `name: optional string` - The workspace ID for a ChatGPT workspace connector resource. + The name of the IP allowlist configuration. - - `"role.created": optional object { id, permissions, resource_id, 2 more }` + - `"ip_allowlist.created": optional object { id, allowed_ips, name }` The details for events with this `type`. - `id: optional string` - The role ID. + The ID of the IP allowlist configuration. - - `permissions: optional array of string` + - `allowed_ips: optional array of string` - The permissions granted by the role. + The IP addresses or CIDR ranges included in the configuration. - - `resource_id: optional string` + - `name: optional string` - The resource the role is scoped to. + The name of the IP allowlist configuration. - - `resource_type: optional string` + - `"ip_allowlist.deleted": optional object { id, allowed_ips, name }` - The type of resource the role belongs to. + The details for events with this `type`. - - `role_name: optional string` + - `id: optional string` - The name of the role. + The ID of the IP allowlist configuration. - - `"role.deleted": optional object { id }` + - `allowed_ips: optional array of string` - The details for events with this `type`. + The IP addresses or CIDR ranges that were in the configuration. - - `id: optional string` + - `name: optional string` - The role ID. + The name of the IP allowlist configuration. - - `"role.unbound_from_resource": optional object { id, connector_id, connector_name, 7 more }` + - `"ip_allowlist.updated": optional object { id, allowed_ips }` The details for events with this `type`. - `id: optional string` - The ID of the resource the role was unbound from. ChatGPT workspace connector resources use `__`. + The ID of the IP allowlist configuration. - - `connector_id: optional string` + - `allowed_ips: optional array of string` - The connector ID for a ChatGPT workspace connector resource. + The updated set of IP addresses or CIDR ranges in the configuration. - - `connector_name: optional string` + - `"login.failed": optional object { error_code, error_message }` - The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. + The details for events with this `type`. - - `enabled: optional boolean` + - `error_code: optional string` - Whether the connector is enabled for the role. + The error code of the failure. - - `permissions: optional array of string` + - `error_message: optional string` - The permissions remaining for the role after the change. + The error message of the failure. - - `resource_id: optional string` + - `"login.succeeded": optional unknown` - The ID of the resource the role was unbound from. + This event has no additional fields beyond the standard audit log attributes. - - `resource_type: optional string` + - `"logout.failed": optional object { error_code, error_message }` - The type of resource the role was unbound from. + The details for events with this `type`. - - `role_id: optional string` + - `error_code: optional string` - The ID of the role that was unbound from the resource. + The error code of the failure. - - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` + - `error_message: optional string` - The connector role mutation path that produced the event. + The error message of the failure. - - `"role_toggle"` + - `"logout.succeeded": optional unknown` - - `"role_connector_update"` - - - `"role_delete"` + This event has no additional fields beyond the standard audit log attributes. - - `"workspace_permissions"` + - `"organization.updated": optional object { id, changes_requested }` - - `"connector_publish"` + The details for events with this `type`. - - `workspace_id: optional string` + - `id: optional string` - The workspace ID for a ChatGPT workspace connector resource. + The organization ID. - - `"role.updated": optional object { id, changes_requested }` + - `changes_requested: optional object { api_call_logging, api_call_logging_project_ids, description, 4 more }` - The details for events with this `type`. + The payload used to update the organization settings. - - `id: optional string` + - `api_call_logging: optional string` - The role ID. + How your organization logs data from supported API calls. One of `disabled`, `enabled_per_call`, `enabled_for_all_projects`, or `enabled_for_selected_projects` - - `changes_requested: optional object { description, metadata, permissions_added, 4 more }` + - `api_call_logging_project_ids: optional string` - The payload used to update the role. + The list of project ids if api_call_logging is set to `enabled_for_selected_projects` - `description: optional string` - The updated role description, when provided. + The organization description. - - `metadata: optional unknown` + - `name: optional string` - Additional metadata stored on the role. + The organization name. - - `permissions_added: optional array of string` + - `threads_ui_visibility: optional string` - The permissions added to the role. + Visibility of the threads page which shows messages created with the Assistants API and Playground. One of `ANY_ROLE`, `OWNERS`, or `NONE`. - - `permissions_removed: optional array of string` + - `title: optional string` - The permissions removed from the role. + The organization title. - - `resource_id: optional string` + - `usage_dashboard_visibility: optional string` - The resource the role is scoped to. + Visibility of the usage dashboard which shows activity and costs for your organization. One of `ANY_ROLE` or `OWNERS`. - - `resource_type: optional string` + - `project: optional object { id, name }` - The type of resource the role belongs to. + The project that the action was scoped to. Absent for actions not scoped to projects. Note that any admin actions taken via Admin API keys are associated with the default project. - - `role_name: optional string` + - `id: optional string` - The updated role name, when provided. + The project ID. - - `"scim.disabled": optional object { id }` + - `name: optional string` + + The project title. + + - `"project.archived": optional object { id }` The details for events with this `type`. - `id: optional string` - The ID of the SCIM was disabled for. + The project ID. - - `"scim.enabled": optional object { id }` + - `"project.created": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The ID of the SCIM was enabled for. + The project ID. - - `"service_account.created": optional object { id, data }` + - `data: optional object { name, title }` + + The payload used to create the project. + + - `name: optional string` + + The project name. + + - `title: optional string` + + The title of the project as seen on the dashboard. + + - `"project.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The service account ID. + The project ID. - - `data: optional object { role }` + - `"project.updated": optional object { id, changes_requested }` - The payload used to create the service account. + The details for events with this `type`. - - `role: optional string` + - `id: optional string` - The role of the service account. Is either `owner` or `member`. + The project ID. - - `"service_account.deleted": optional object { id }` + - `changes_requested: optional object { title }` + + The payload used to update the project. + + - `title: optional string` + + The title of the project as seen on the dashboard. + + - `"rate_limit.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The service account ID. + The rate limit ID - - `"service_account.updated": optional object { id, changes_requested }` + - `"rate_limit.updated": optional object { id, changes_requested }` The details for events with this `type`. - `id: optional string` - The service account ID. + The rate limit ID - - `changes_requested: optional object { role }` + - `changes_requested: optional object { batch_1_day_max_input_tokens, max_audio_megabytes_per_1_minute, max_images_per_1_minute, 3 more }` - The payload used to updated the service account. + The payload used to update the rate limits. - - `role: optional string` + - `batch_1_day_max_input_tokens: optional number` - The role of the service account. Is either `owner` or `member`. + The maximum batch input tokens per day. Only relevant for certain models. - - `"user.added": optional object { id, data }` + - `max_audio_megabytes_per_1_minute: optional number` - The details for events with this `type`. + The maximum audio megabytes per minute. Only relevant for certain models. - - `id: optional string` + - `max_images_per_1_minute: optional number` - The user ID. + The maximum images per minute. Only relevant for certain models. - - `data: optional object { role }` + - `max_requests_per_1_day: optional number` - The payload used to add the user to the project. + The maximum requests per day. Only relevant for certain models. - - `role: optional string` + - `max_requests_per_1_minute: optional number` - The role of the user. Is either `owner` or `member`. + The maximum requests per minute. - - `"user.deleted": optional object { id }` + - `max_tokens_per_1_minute: optional number` + + The maximum tokens per minute. + + - `"role.assignment.created": optional object { id, principal_id, principal_type, 2 more }` The details for events with this `type`. - `id: optional string` - The user ID. + The identifier of the role assignment. - - `"user.updated": optional object { id, changes_requested }` + - `principal_id: optional string` - The details for events with this `type`. + The principal (user or group) that received the role. - - `id: optional string` + - `principal_type: optional string` - The project ID. + The type of principal (user or group) that received the role. - - `changes_requested: optional object { role }` + - `resource_id: optional string` - The payload used to update the user. + The resource the role assignment is scoped to. - - `role: optional string` + - `resource_type: optional string` - The role of the user. Is either `owner` or `member`. + The type of resource the role assignment is scoped to. - - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }` + - `"role.assignment.deleted": optional object { id, principal_id, principal_type, 2 more }` The details for events with this `type`. - `id: optional string` - The workload identity provider mapping ID. + The identifier of the role assignment. - - `data: optional unknown` + - `principal_id: optional string` - The payload used to create the workload identity provider mapping. + The principal (user or group) that had the role removed. - - `identity_provider_id: optional string` + - `principal_type: optional string` - The workload identity provider ID. + The type of principal (user or group) that had the role removed. - - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }` + - `resource_id: optional string` + + The resource the role assignment was scoped to. + + - `resource_type: optional string` + + The type of resource the role assignment was scoped to. + + - `"role.bound_to_resource": optional object { id, connector_id, connector_name, 7 more }` The details for events with this `type`. - `id: optional string` - The workload identity provider mapping ID. + The ID of the resource the role was bound to. ChatGPT workspace connector resources use `__`. - - `identity_provider_id: optional string` + - `connector_id: optional string` - The workload identity provider ID. + The connector ID for a ChatGPT workspace connector resource. - - `project_id: optional string` + - `connector_name: optional string` - The project ID. + The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. - - `service_account_id: optional string` + - `enabled: optional boolean` - The mapped service account ID. + Whether the connector is enabled for the role. - - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }` + - `permissions: optional array of string` - The details for events with this `type`. + The permissions granted to the role for the resource. - - `id: optional string` + - `resource_id: optional string` - The workload identity provider mapping ID. + The ID of the resource the role was bound to. - - `changes_requested: optional unknown` + - `resource_type: optional string` - The payload used to update the workload identity provider mapping. + The type of resource the role was bound to. - - `identity_provider_id: optional string` + - `role_id: optional string` - The workload identity provider ID. + The ID of the role that was bound to the resource. - - `"workload_identity_provider.created": optional object { id, data }` + - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` - The details for events with this `type`. + The connector role mutation path that produced the event. - - `id: optional string` + - `"role_toggle"` - The workload identity provider ID. + - `"role_connector_update"` - - `data: optional unknown` + - `"role_delete"` - The payload used to create the workload identity provider. + - `"workspace_permissions"` - - `"workload_identity_provider.deleted": optional object { id, name }` + - `"connector_publish"` + + - `workspace_id: optional string` + + The workspace ID for a ChatGPT workspace connector resource. + + - `"role.created": optional object { id, permissions, resource_id, 2 more }` The details for events with this `type`. - `id: optional string` - The workload identity provider ID. + The role ID. - - `name: optional string` + - `permissions: optional array of string` - The workload identity provider name. + The permissions granted by the role. - - `"workload_identity_provider.updated": optional object { id, changes_requested }` + - `resource_id: optional string` - The details for events with this `type`. + The resource the role is scoped to. - - `id: optional string` + - `resource_type: optional string` - The workload identity provider ID. + The type of resource the role belongs to. - - `changes_requested: optional unknown` + - `role_name: optional string` - The payload used to update the workload identity provider. + The name of the role. -- `has_more: boolean` + - `"role.deleted": optional object { id }` -- `object: "list"` + The details for events with this `type`. - - `"list"` + - `id: optional string` -- `first_id: optional string` + The role ID. -- `last_id: optional string` + - `"role.unbound_from_resource": optional object { id, connector_id, connector_name, 7 more }` -### Example + The details for events with this `type`. -```http -curl https://api.openai.com/v1/organization/audit_logs \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `id: optional string` -#### Response - -```json -{ - "data": [ - { - "id": "id", - "effective_at": 0, - "type": "api_key.created", - "actor": { - "api_key": { - "id": "id", - "service_account": { - "id": "id" - }, - "type": "user", - "user": { - "id": "id", - "email": "email" - } - }, - "session": { - "ip_address": "ip_address", - "user": { - "id": "id", - "email": "email" - } - }, - "type": "session" - }, - "api_key.created": { - "id": "id", - "data": { - "scopes": [ - "string" - ] - } - }, - "api_key.deleted": { - "id": "id" - }, - "api_key.updated": { - "id": "id", - "changes_requested": { - "scopes": [ - "string" - ] - } - }, - "certificate.created": { - "id": "id", - "name": "name" - }, - "certificate.deleted": { - "id": "id", - "certificate": "certificate", - "name": "name" - }, - "certificate.updated": { - "id": "id", - "name": "name" - }, - "certificates.activated": { - "certificates": [ - { - "id": "id", - "name": "name" - } - ] - }, - "certificates.deactivated": { - "certificates": [ - { - "id": "id", - "name": "name" - } - ] - }, - "checkpoint.permission.created": { - "id": "id", - "data": { - "fine_tuned_model_checkpoint": "fine_tuned_model_checkpoint", - "project_id": "project_id" - } - }, - "checkpoint.permission.deleted": { - "id": "id" - }, - "external_key.registered": { - "id": "id", - "data": {} - }, - "external_key.removed": { - "id": "id" - }, - "group.created": { - "id": "id", - "data": { - "group_name": "group_name" - } - }, - "group.deleted": { - "id": "id" - }, - "group.updated": { - "id": "id", - "changes_requested": { - "group_name": "group_name" - } - }, - "invite.accepted": { - "id": "id" - }, - "invite.deleted": { - "id": "id" - }, - "invite.sent": { - "id": "id", - "data": { - "email": "email", - "role": "role" - } - }, - "ip_allowlist.config.activated": { - "configs": [ - { - "id": "id", - "name": "name" - } - ] - }, - "ip_allowlist.config.deactivated": { - "configs": [ - { - "id": "id", - "name": "name" - } - ] - }, - "ip_allowlist.created": { - "id": "id", - "allowed_ips": [ - "string" - ], - "name": "name" - }, - "ip_allowlist.deleted": { - "id": "id", - "allowed_ips": [ - "string" - ], - "name": "name" - }, - "ip_allowlist.updated": { - "id": "id", - "allowed_ips": [ - "string" - ] - }, - "login.failed": { - "error_code": "error_code", - "error_message": "error_message" - }, - "login.succeeded": {}, - "logout.failed": { - "error_code": "error_code", - "error_message": "error_message" - }, - "logout.succeeded": {}, - "organization.updated": { - "id": "id", - "changes_requested": { - "api_call_logging": "api_call_logging", - "api_call_logging_project_ids": "api_call_logging_project_ids", - "description": "description", - "name": "name", - "threads_ui_visibility": "threads_ui_visibility", - "title": "title", - "usage_dashboard_visibility": "usage_dashboard_visibility" - } - }, - "project": { - "id": "id", - "name": "name" - }, - "project.archived": { - "id": "id" - }, - "project.created": { - "id": "id", - "data": { - "name": "name", - "title": "title" - } - }, - "project.deleted": { - "id": "id" - }, - "project.updated": { - "id": "id", - "changes_requested": { - "title": "title" - } - }, - "rate_limit.deleted": { - "id": "id" - }, - "rate_limit.updated": { - "id": "id", - "changes_requested": { - "batch_1_day_max_input_tokens": 0, - "max_audio_megabytes_per_1_minute": 0, - "max_images_per_1_minute": 0, - "max_requests_per_1_day": 0, - "max_requests_per_1_minute": 0, - "max_tokens_per_1_minute": 0 - } - }, - "role.assignment.created": { - "id": "id", - "principal_id": "principal_id", - "principal_type": "principal_type", - "resource_id": "resource_id", - "resource_type": "resource_type" - }, - "role.assignment.deleted": { - "id": "id", - "principal_id": "principal_id", - "principal_type": "principal_type", - "resource_id": "resource_id", - "resource_type": "resource_type" - }, - "role.bound_to_resource": { - "id": "id", - "connector_id": "connector_id", - "connector_name": "connector_name", - "enabled": true, - "permissions": [ - "string" - ], - "resource_id": "resource_id", - "resource_type": "resource_type", - "role_id": "role_id", - "source": "role_toggle", - "workspace_id": "workspace_id" - }, - "role.created": { - "id": "id", - "permissions": [ - "string" - ], - "resource_id": "resource_id", - "resource_type": "resource_type", - "role_name": "role_name" - }, - "role.deleted": { - "id": "id" - }, - "role.unbound_from_resource": { - "id": "id", - "connector_id": "connector_id", - "connector_name": "connector_name", - "enabled": true, - "permissions": [ - "string" - ], - "resource_id": "resource_id", - "resource_type": "resource_type", - "role_id": "role_id", - "source": "role_toggle", - "workspace_id": "workspace_id" - }, - "role.updated": { - "id": "id", - "changes_requested": { - "description": "description", - "metadata": {}, - "permissions_added": [ - "string" - ], - "permissions_removed": [ - "string" - ], - "resource_id": "resource_id", - "resource_type": "resource_type", - "role_name": "role_name" - } - }, - "scim.disabled": { - "id": "id" - }, - "scim.enabled": { - "id": "id" - }, - "service_account.created": { - "id": "id", - "data": { - "role": "role" - } - }, - "service_account.deleted": { - "id": "id" - }, - "service_account.updated": { - "id": "id", - "changes_requested": { - "role": "role" - } - }, - "user.added": { - "id": "id", - "data": { - "role": "role" - } - }, - "user.deleted": { - "id": "id" - }, - "user.updated": { - "id": "id", - "changes_requested": { - "role": "role" - } - }, - "workload_identity_provider_mapping.created": { - "id": "id", - "data": {}, - "identity_provider_id": "identity_provider_id" - }, - "workload_identity_provider_mapping.deleted": { - "id": "id", - "identity_provider_id": "identity_provider_id", - "project_id": "project_id", - "service_account_id": "service_account_id" - }, - "workload_identity_provider_mapping.updated": { - "id": "id", - "changes_requested": {}, - "identity_provider_id": "identity_provider_id" - }, - "workload_identity_provider.created": { - "id": "id", - "data": {} - }, - "workload_identity_provider.deleted": { - "id": "id", - "name": "name" - }, - "workload_identity_provider.updated": { - "id": "id", - "changes_requested": {} - } - } - ], - "has_more": true, - "object": "list", - "first_id": "audit_log-defb456h8dks", - "last_id": "audit_log-hnbkd8s93s" -} -``` - -### Example - -```http -curl https://api.openai.com/v1/organization/audit_logs \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" -``` - -#### Response - -```json -{ - "object": "list", - "data": [ - { - "id": "audit_log-xxx_yyyymmdd", - "type": "project.archived", - "effective_at": 1722461446, - "actor": { - "type": "api_key", - "api_key": { - "type": "user", - "user": { - "id": "user-xxx", - "email": "user@example.com" - } - } - }, - "project.archived": { - "id": "proj_abc" - }, - }, - { - "id": "audit_log-yyy__20240101", - "type": "api_key.updated", - "effective_at": 1720804190, - "actor": { - "type": "session", - "session": { - "user": { - "id": "user-xxx", - "email": "user@example.com" - }, - "ip_address": "127.0.0.1", - "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36", - "ja3": "a497151ce4338a12c4418c44d375173e", - "ja4": "q13d0313h3_55b375c5d22e_c7319ce65786", - "ip_address_details": { - "country": "US", - "city": "San Francisco", - "region": "California", - "region_code": "CA", - "asn": "1234", - "latitude": "37.77490", - "longitude": "-122.41940" - } - } - }, - "api_key.updated": { - "id": "key_xxxx", - "data": { - "scopes": ["resource_2.operation_2"] - } - }, - } - ], - "first_id": "audit_log-xxx__20240101", - "last_id": "audit_log_yyy__20240101", - "has_more": true -} -``` - -## Domain Types - -### Audit Log List Response - -- `AuditLogListResponse object { id, effective_at, type, 57 more }` - - A log of a user action or configuration change within this organization. - - - `id: string` - - The ID of this log. - - - `effective_at: number` - - The Unix timestamp (in seconds) of the event. - - - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` - - The event type. - - - `"api_key.created"` - - - `"api_key.updated"` - - - `"api_key.deleted"` - - - `"certificate.created"` - - - `"certificate.updated"` - - - `"certificate.deleted"` - - - `"certificates.activated"` - - - `"certificates.deactivated"` - - - `"checkpoint.permission.created"` - - - `"checkpoint.permission.deleted"` - - - `"external_key.registered"` - - - `"external_key.removed"` - - - `"group.created"` - - - `"group.updated"` - - - `"group.deleted"` - - - `"invite.sent"` - - - `"invite.accepted"` - - - `"invite.deleted"` - - - `"ip_allowlist.created"` - - - `"ip_allowlist.updated"` - - - `"ip_allowlist.deleted"` - - - `"ip_allowlist.config.activated"` - - - `"ip_allowlist.config.deactivated"` - - - `"login.succeeded"` - - - `"login.failed"` - - - `"logout.succeeded"` - - - `"logout.failed"` - - - `"organization.updated"` - - - `"project.created"` - - - `"project.updated"` - - - `"project.archived"` - - - `"project.deleted"` - - - `"rate_limit.updated"` - - - `"rate_limit.deleted"` - - - `"resource.deleted"` - - - `"tunnel.created"` - - - `"tunnel.updated"` - - - `"tunnel.deleted"` - - - `"workload_identity_provider.created"` - - - `"workload_identity_provider.updated"` - - - `"workload_identity_provider.deleted"` - - - `"workload_identity_provider_mapping.created"` - - - `"workload_identity_provider_mapping.updated"` - - - `"workload_identity_provider_mapping.deleted"` - - - `"role.created"` - - - `"role.updated"` - - - `"role.deleted"` - - - `"role.assignment.created"` - - - `"role.assignment.deleted"` - - - `"role.bound_to_resource"` - - - `"role.unbound_from_resource"` - - - `"scim.enabled"` - - - `"scim.disabled"` - - - `"service_account.created"` - - - `"service_account.updated"` - - - `"service_account.deleted"` - - - `"user.added"` - - - `"user.updated"` - - - `"user.deleted"` - - - `"tenant.metadata.updated"` - - - `"tenant.microsoft_entra_mapping.upserted"` - - - `"tenant.microsoft_entra_mapping.deleted"` - - - `"tenant.workload_identity.provider.created"` - - - `"tenant.workload_identity.provider.updated"` - - - `"tenant.workload_identity.provider.archived"` - - - `"tenant.workload_identity.mapping.created"` - - - `"tenant.workload_identity.mapping.updated"` - - - `"tenant.workload_identity.mapping.archived"` - - - `"tenant.workload_identity.binding.created"` - - - `"tenant.workload_identity.principal.provisioned"` - - - `"tenant.admin_api_key.created"` - - - `"tenant.admin_api_key.updated"` - - - `"tenant.admin_api_key.deleted"` - - - `"tenant.project_api_key.created"` - - - `"tenant.chatgpt_access_token.revoked"` - - - `"tenant.migration.completed"` - - - `"tenant.sso.migrated"` - - - `"tenant.domains.migrated"` - - - `"tenant.sso_connection.created"` - - - `"tenant.sso_connection.updated"` - - - `"tenant.sso_connection.deleted"` - - - `"tenant.sso_connection.setup.started"` - - - `"tenant.policy.created"` - - - `"tenant.policy.updated"` - - - `"tenant.policy.deleted"` - - - `"tenant.policy.attached"` + The ID of the resource the role was unbound from. ChatGPT workspace connector resources use `__`. - - `"tenant.policy.detached"` + - `connector_id: optional string` - - `"tenant.principal_authentication_policy.resolved"` + The connector ID for a ChatGPT workspace connector resource. - - `"tenant.scim.setup.started"` + - `connector_name: optional string` - - `"tenant.scim.deletion.requested"` + The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. - - `"tenant.scim.directory.created"` + - `enabled: optional boolean` - - `"tenant.product_access_policy.updated"` + Whether the connector is enabled for the role. - - `"tenant.resource_share_grant.created"` + - `permissions: optional array of string` - - `"tenant.resource_share_grant.updated"` + The permissions remaining for the role after the change. - - `"tenant.resource_share_grant.accepted"` + - `resource_id: optional string` - - `"tenant.resource_share_grant.declined"` + The ID of the resource the role was unbound from. - - `"tenant.resource_share_grant.revoked"` + - `resource_type: optional string` - - `"tenant.resource_share_grant.deleted"` + The type of resource the role was unbound from. - - `"tenant.service_account.updated"` + - `role_id: optional string` - - `"tenant.service_account.deleted"` + The ID of the role that was unbound from the resource. - - `"tenant.service_account.token.revoked"` + - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` - - `"tenant.billing.overage_limit.updated"` + The connector role mutation path that produced the event. - - `"tenant.billing.alerts.updated"` + - `"role_toggle"` - - `"tenant.billing.info.updated"` + - `"role_connector_update"` - - `"tenant.usage_limit.workspace.updated"` + - `"role_delete"` - - `"tenant.usage_limit.group.updated"` + - `"workspace_permissions"` - - `"tenant.usage_limit.user.updated"` + - `"connector_publish"` - - `"tenant.usage_limit.increase_request.updated"` + - `workspace_id: optional string` - - `"tenant.usage_limit.increase_request.resolved"` + The workspace ID for a ChatGPT workspace connector resource. - - `"tenant.group.created"` + - `"role.updated": optional object { id, changes_requested }` - - `"tenant.group.updated"` + The details for events with this `type`. - - `"tenant.group.deleted"` + - `id: optional string` - - `"tenant.group.member.added"` + The role ID. - - `"tenant.group.member.removed"` + - `changes_requested: optional object { description, metadata, permissions_added, 4 more }` - - `"tenant.migration_rollout.status.updated"` + The payload used to update the role. - - `"tenant.migration_rollout.tier.updated"` + - `description: optional string` - - `"tenant.role.metadata.updated"` + The updated role description, when provided. - - `"tenant.custom_role.created"` + - `metadata: optional unknown` - - `"tenant.custom_role.updated"` + Additional metadata stored on the role. - - `"tenant.custom_role.deleted"` + - `permissions_added: optional array of string` - - `"tenant.role_assignment.created"` + The permissions added to the role. - - `"tenant.role_assignment.deleted"` + - `permissions_removed: optional array of string` - - `"tenant.resource_role_assignment.created"` + The permissions removed from the role. - - `"tenant.resource_role_assignment.deleted"` + - `resource_id: optional string` - - `"tenant.resource_access.updated"` + The resource the role is scoped to. - - `"tenant.resource_access.deleted"` + - `resource_type: optional string` - - `"tenant.session_policy.created"` + The type of resource the role belongs to. - - `"tenant.session_policy.updated"` + - `role_name: optional string` - - `"tenant.session_policy.deleted"` + The updated role name, when provided. - - `"tenant.session_revocation.started"` + - `"scim.disabled": optional object { id }` - - `"tenant.third_party_app_policy.updated"` + The details for events with this `type`. - - `"tenant.user.added"` + - `id: optional string` - - `"tenant.user.updated"` + The ID of the SCIM was disabled for. - - `"tenant.user.removed"` + - `"scim.enabled": optional object { id }` - - `"tenant.user.looked_up"` + The details for events with this `type`. - - `"tenant.user.invited"` + - `id: optional string` - - `"tenant.membership.revoked"` + The ID of the SCIM was enabled for. - - `"tenant.api_organization_invite.upserted"` + - `"service_account.created": optional object { id, data }` - - `"tenant.api_organization_invite.deleted"` + The details for events with this `type`. - - `"tenant.chatgpt_workspace_invite.upserted"` + - `id: optional string` - - `"tenant.membership.accepted"` + The service account ID. - - `"tenant.membership.declined"` + - `data: optional object { role }` - - `"tenant.workspace_invite_email_settings.updated"` + The payload used to create the service account. - - `actor: optional object { api_key, session, type }` + - `role: optional string` - The actor who performed the audit logged action. + The role of the service account. Is either `owner` or `member`. - - `api_key: optional object { id, service_account, type, user }` + - `"service_account.deleted": optional object { id }` - The API Key used to perform the audit logged action. + The details for events with this `type`. - `id: optional string` - The tracking id of the API key. + The service account ID. - - `service_account: optional object { id }` + - `"service_account.updated": optional object { id, changes_requested }` - The service account that performed the audit logged action. + The details for events with this `type`. - `id: optional string` - The service account id. + The service account ID. - - `type: optional "user" or "service_account"` + - `changes_requested: optional object { role }` - The type of API key. Can be either `user` or `service_account`. + The payload used to updated the service account. - - `"user"` + - `role: optional string` - - `"service_account"` + The role of the service account. Is either `owner` or `member`. - - `user: optional object { id, email }` + - `"user.added": optional object { id, data }` - The user who performed the audit logged action. + The details for events with this `type`. - `id: optional string` - The user id. - - - `email: optional string` - - The user email. + The user ID. - - `session: optional object { ip_address, user }` + - `data: optional object { role }` - The session in which the audit logged action was performed. + The payload used to add the user to the project. - - `ip_address: optional string` + - `role: optional string` - The IP address from which the action was performed. + The role of the user. Is either `owner` or `member`. - - `user: optional object { id, email }` + - `"user.deleted": optional object { id }` - The user who performed the audit logged action. + The details for events with this `type`. - `id: optional string` - The user id. - - - `email: optional string` - - The user email. - - - `type: optional "session" or "api_key"` - - The type of actor. Is either `session` or `api_key`. - - - `"session"` - - - `"api_key"` + The user ID. - - `"api_key.created": optional object { id, data }` + - `"user.updated": optional object { id, changes_requested }` The details for events with this `type`. - `id: optional string` - The tracking ID of the API key. - - - `data: optional object { scopes }` - - The payload used to create the API key. - - - `scopes: optional array of string` - - A list of scopes allowed for the API key, e.g. `["api.model.request"]` + The project ID. - - `"api_key.deleted": optional object { id }` + - `changes_requested: optional object { role }` - The details for events with this `type`. + The payload used to update the user. - - `id: optional string` + - `role: optional string` - The tracking ID of the API key. + The role of the user. Is either `owner` or `member`. - - `"api_key.updated": optional object { id, changes_requested }` + - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }` The details for events with this `type`. - `id: optional string` - The tracking ID of the API key. + The workload identity provider mapping ID. - - `changes_requested: optional object { scopes }` + - `data: optional unknown` - The payload used to update the API key. + The payload used to create the workload identity provider mapping. - - `scopes: optional array of string` + - `identity_provider_id: optional string` - A list of scopes allowed for the API key, e.g. `["api.model.request"]` + The workload identity provider ID. - - `"certificate.created": optional object { id, name }` + - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }` The details for events with this `type`. - `id: optional string` - The certificate ID. + The workload identity provider mapping ID. - - `name: optional string` + - `identity_provider_id: optional string` - The name of the certificate. + The workload identity provider ID. - - `"certificate.deleted": optional object { id, certificate, name }` + - `project_id: optional string` + + The project ID. + + - `service_account_id: optional string` + + The mapped service account ID. + + - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }` The details for events with this `type`. - `id: optional string` - The certificate ID. + The workload identity provider mapping ID. - - `certificate: optional string` + - `changes_requested: optional unknown` - The certificate content in PEM format. + The payload used to update the workload identity provider mapping. - - `name: optional string` + - `identity_provider_id: optional string` - The name of the certificate. + The workload identity provider ID. - - `"certificate.updated": optional object { id, name }` + - `"workload_identity_provider.created": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The certificate ID. + The workload identity provider ID. - - `name: optional string` + - `data: optional unknown` - The name of the certificate. + The payload used to create the workload identity provider. - - `"certificates.activated": optional object { certificates }` + - `"workload_identity_provider.deleted": optional object { id, name }` The details for events with this `type`. - - `certificates: optional array of object { id, name }` - - `id: optional string` - The certificate ID. + The workload identity provider ID. - `name: optional string` - The name of the certificate. + The workload identity provider name. - - `"certificates.deactivated": optional object { certificates }` + - `"workload_identity_provider.updated": optional object { id, changes_requested }` The details for events with this `type`. - - `certificates: optional array of object { id, name }` - - `id: optional string` - The certificate ID. + The workload identity provider ID. - - `name: optional string` + - `changes_requested: optional unknown` - The name of the certificate. + The payload used to update the workload identity provider. - - `"checkpoint.permission.created": optional object { id, data }` +- `has_more: boolean` - The project and fine-tuned model checkpoint that the checkpoint permission was created for. +- `object: "list"` - - `id: optional string` + - `"list"` - The ID of the checkpoint permission. +- `first_id: optional string` - - `data: optional object { fine_tuned_model_checkpoint, project_id }` +- `last_id: optional string` - The payload used to create the checkpoint permission. +### Example - - `fine_tuned_model_checkpoint: optional string` +```http +curl https://api.openai.com/v1/organization/audit_logs \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The ID of the fine-tuned model checkpoint. +#### Response - - `project_id: optional string` +```json +{ + "data": [ + { + "id": "id", + "effective_at": 0, + "type": "api_key.created", + "actor": { + "api_key": { + "id": "id", + "service_account": { + "id": "id" + }, + "type": "user", + "user": { + "id": "id", + "email": "email" + } + }, + "session": { + "ip_address": "ip_address", + "user": { + "id": "id", + "email": "email" + } + }, + "type": "session" + }, + "api_key.created": { + "id": "id", + "data": { + "scopes": [ + "string" + ] + } + }, + "api_key.deleted": { + "id": "id" + }, + "api_key.updated": { + "id": "id", + "changes_requested": { + "scopes": [ + "string" + ] + } + }, + "certificate.created": { + "id": "id", + "name": "name" + }, + "certificate.deleted": { + "id": "id", + "certificate": "certificate", + "name": "name" + }, + "certificate.updated": { + "id": "id", + "name": "name" + }, + "certificates.activated": { + "certificates": [ + { + "id": "id", + "name": "name" + } + ] + }, + "certificates.deactivated": { + "certificates": [ + { + "id": "id", + "name": "name" + } + ] + }, + "checkpoint.permission.created": { + "id": "id", + "data": { + "fine_tuned_model_checkpoint": "fine_tuned_model_checkpoint", + "project_id": "project_id" + } + }, + "checkpoint.permission.deleted": { + "id": "id" + }, + "external_key.registered": { + "id": "id", + "data": {} + }, + "external_key.removed": { + "id": "id" + }, + "group.created": { + "id": "id", + "data": { + "group_name": "group_name" + } + }, + "group.deleted": { + "id": "id" + }, + "group.updated": { + "id": "id", + "changes_requested": { + "group_name": "group_name" + } + }, + "invite.accepted": { + "id": "id" + }, + "invite.deleted": { + "id": "id" + }, + "invite.sent": { + "id": "id", + "data": { + "email": "email", + "role": "role" + } + }, + "ip_allowlist.config.activated": { + "configs": [ + { + "id": "id", + "name": "name" + } + ] + }, + "ip_allowlist.config.deactivated": { + "configs": [ + { + "id": "id", + "name": "name" + } + ] + }, + "ip_allowlist.created": { + "id": "id", + "allowed_ips": [ + "string" + ], + "name": "name" + }, + "ip_allowlist.deleted": { + "id": "id", + "allowed_ips": [ + "string" + ], + "name": "name" + }, + "ip_allowlist.updated": { + "id": "id", + "allowed_ips": [ + "string" + ] + }, + "login.failed": { + "error_code": "error_code", + "error_message": "error_message" + }, + "login.succeeded": {}, + "logout.failed": { + "error_code": "error_code", + "error_message": "error_message" + }, + "logout.succeeded": {}, + "organization.updated": { + "id": "id", + "changes_requested": { + "api_call_logging": "api_call_logging", + "api_call_logging_project_ids": "api_call_logging_project_ids", + "description": "description", + "name": "name", + "threads_ui_visibility": "threads_ui_visibility", + "title": "title", + "usage_dashboard_visibility": "usage_dashboard_visibility" + } + }, + "project": { + "id": "id", + "name": "name" + }, + "project.archived": { + "id": "id" + }, + "project.created": { + "id": "id", + "data": { + "name": "name", + "title": "title" + } + }, + "project.deleted": { + "id": "id" + }, + "project.updated": { + "id": "id", + "changes_requested": { + "title": "title" + } + }, + "rate_limit.deleted": { + "id": "id" + }, + "rate_limit.updated": { + "id": "id", + "changes_requested": { + "batch_1_day_max_input_tokens": 0, + "max_audio_megabytes_per_1_minute": 0, + "max_images_per_1_minute": 0, + "max_requests_per_1_day": 0, + "max_requests_per_1_minute": 0, + "max_tokens_per_1_minute": 0 + } + }, + "role.assignment.created": { + "id": "id", + "principal_id": "principal_id", + "principal_type": "principal_type", + "resource_id": "resource_id", + "resource_type": "resource_type" + }, + "role.assignment.deleted": { + "id": "id", + "principal_id": "principal_id", + "principal_type": "principal_type", + "resource_id": "resource_id", + "resource_type": "resource_type" + }, + "role.bound_to_resource": { + "id": "id", + "connector_id": "connector_id", + "connector_name": "connector_name", + "enabled": true, + "permissions": [ + "string" + ], + "resource_id": "resource_id", + "resource_type": "resource_type", + "role_id": "role_id", + "source": "role_toggle", + "workspace_id": "workspace_id" + }, + "role.created": { + "id": "id", + "permissions": [ + "string" + ], + "resource_id": "resource_id", + "resource_type": "resource_type", + "role_name": "role_name" + }, + "role.deleted": { + "id": "id" + }, + "role.unbound_from_resource": { + "id": "id", + "connector_id": "connector_id", + "connector_name": "connector_name", + "enabled": true, + "permissions": [ + "string" + ], + "resource_id": "resource_id", + "resource_type": "resource_type", + "role_id": "role_id", + "source": "role_toggle", + "workspace_id": "workspace_id" + }, + "role.updated": { + "id": "id", + "changes_requested": { + "description": "description", + "metadata": {}, + "permissions_added": [ + "string" + ], + "permissions_removed": [ + "string" + ], + "resource_id": "resource_id", + "resource_type": "resource_type", + "role_name": "role_name" + } + }, + "scim.disabled": { + "id": "id" + }, + "scim.enabled": { + "id": "id" + }, + "service_account.created": { + "id": "id", + "data": { + "role": "role" + } + }, + "service_account.deleted": { + "id": "id" + }, + "service_account.updated": { + "id": "id", + "changes_requested": { + "role": "role" + } + }, + "user.added": { + "id": "id", + "data": { + "role": "role" + } + }, + "user.deleted": { + "id": "id" + }, + "user.updated": { + "id": "id", + "changes_requested": { + "role": "role" + } + }, + "workload_identity_provider_mapping.created": { + "id": "id", + "data": {}, + "identity_provider_id": "identity_provider_id" + }, + "workload_identity_provider_mapping.deleted": { + "id": "id", + "identity_provider_id": "identity_provider_id", + "project_id": "project_id", + "service_account_id": "service_account_id" + }, + "workload_identity_provider_mapping.updated": { + "id": "id", + "changes_requested": {}, + "identity_provider_id": "identity_provider_id" + }, + "workload_identity_provider.created": { + "id": "id", + "data": {} + }, + "workload_identity_provider.deleted": { + "id": "id", + "name": "name" + }, + "workload_identity_provider.updated": { + "id": "id", + "changes_requested": {} + } + } + ], + "has_more": true, + "object": "list", + "first_id": "audit_log-defb456h8dks", + "last_id": "audit_log-hnbkd8s93s" +} +``` - The ID of the project that the checkpoint permission was created for. +### Example - - `"checkpoint.permission.deleted": optional object { id }` +```http +curl https://api.openai.com/v1/organization/audit_logs \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" +``` - The details for events with this `type`. +#### Response - - `id: optional string` +```json +{ + "object": "list", + "data": [ + { + "id": "audit_log-xxx_yyyymmdd", + "type": "project.archived", + "effective_at": 1722461446, + "actor": { + "type": "api_key", + "api_key": { + "type": "user", + "user": { + "id": "user-xxx", + "email": "user@example.com" + } + } + }, + "project.archived": { + "id": "proj_abc" + }, + }, + { + "id": "audit_log-yyy__20240101", + "type": "api_key.updated", + "effective_at": 1720804190, + "actor": { + "type": "session", + "session": { + "user": { + "id": "user-xxx", + "email": "user@example.com" + }, + "ip_address": "127.0.0.1", + "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36", + "ja3": "a497151ce4338a12c4418c44d375173e", + "ja4": "q13d0313h3_55b375c5d22e_c7319ce65786", + "ip_address_details": { + "country": "US", + "city": "San Francisco", + "region": "California", + "region_code": "CA", + "asn": "1234", + "latitude": "37.77490", + "longitude": "-122.41940" + } + } + }, + "api_key.updated": { + "id": "key_xxxx", + "data": { + "scopes": ["resource_2.operation_2"] + } + }, + } + ], + "first_id": "audit_log-xxx__20240101", + "last_id": "audit_log_yyy__20240101", + "has_more": true +} +``` - The ID of the checkpoint permission. +## Domain Types - - `"external_key.registered": optional object { id, data }` +### Audit Log List Response - The details for events with this `type`. +- `AuditLogListResponse object { id, effective_at, type, 57 more }` - - `id: optional string` + A log of a user action or configuration change within this organization. - The ID of the external key configuration. + - `id: string` - - `data: optional unknown` + The ID of this log. - The configuration for the external key. + - `effective_at: number` - - `"external_key.removed": optional object { id }` + The Unix timestamp (in seconds) of the event. - The details for events with this `type`. + - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 140 more` - - `id: optional string` + The event type. - The ID of the external key configuration. + - `"api_key.created"` - - `"group.created": optional object { id, data }` + - `"api_key.updated"` - The details for events with this `type`. + - `"api_key.deleted"` - - `id: optional string` + - `"certificate.created"` - The ID of the group. + - `"certificate.updated"` - - `data: optional object { group_name }` + - `"certificate.deleted"` - Information about the created group. + - `"certificates.activated"` - - `group_name: optional string` + - `"certificates.deactivated"` - The group name. + - `"checkpoint.permission.created"` - - `"group.deleted": optional object { id }` + - `"checkpoint.permission.deleted"` - The details for events with this `type`. + - `"external_key.registered"` - - `id: optional string` + - `"external_key.removed"` - The ID of the group. + - `"group.created"` - - `"group.updated": optional object { id, changes_requested }` + - `"group.updated"` - The details for events with this `type`. + - `"group.deleted"` - - `id: optional string` + - `"invite.sent"` - The ID of the group. + - `"invite.accepted"` - - `changes_requested: optional object { group_name }` + - `"invite.deleted"` - The payload used to update the group. + - `"ip_allowlist.created"` - - `group_name: optional string` + - `"ip_allowlist.updated"` - The updated group name. + - `"ip_allowlist.deleted"` - - `"invite.accepted": optional object { id }` + - `"ip_allowlist.config.activated"` - The details for events with this `type`. + - `"ip_allowlist.config.deactivated"` - - `id: optional string` + - `"login.succeeded"` - The ID of the invite. + - `"login.failed"` - - `"invite.deleted": optional object { id }` + - `"logout.succeeded"` - The details for events with this `type`. + - `"logout.failed"` - - `id: optional string` + - `"organization.updated"` - The ID of the invite. + - `"project.created"` - - `"invite.sent": optional object { id, data }` + - `"project.updated"` - The details for events with this `type`. + - `"project.archived"` - - `id: optional string` + - `"project.deleted"` - The ID of the invite. + - `"rate_limit.updated"` - - `data: optional object { email, role }` + - `"rate_limit.deleted"` - The payload used to create the invite. + - `"resource.deleted"` - - `email: optional string` + - `"tunnel.created"` - The email invited to the organization. + - `"tunnel.updated"` - - `role: optional string` + - `"tunnel.deleted"` - The role the email was invited to be. Is either `owner` or `member`. + - `"workload_identity_provider.created"` - - `"ip_allowlist.config.activated": optional object { configs }` + - `"workload_identity_provider.updated"` - The details for events with this `type`. + - `"workload_identity_provider.deleted"` - - `configs: optional array of object { id, name }` + - `"workload_identity_provider_mapping.created"` - The configurations that were activated. + - `"workload_identity_provider_mapping.updated"` - - `id: optional string` + - `"workload_identity_provider_mapping.deleted"` - The ID of the IP allowlist configuration. + - `"role.created"` - - `name: optional string` + - `"role.updated"` - The name of the IP allowlist configuration. + - `"role.deleted"` - - `"ip_allowlist.config.deactivated": optional object { configs }` + - `"role.assignment.created"` - The details for events with this `type`. + - `"role.assignment.deleted"` - - `configs: optional array of object { id, name }` + - `"role.bound_to_resource"` - The configurations that were deactivated. + - `"role.unbound_from_resource"` - - `id: optional string` + - `"scim.enabled"` - The ID of the IP allowlist configuration. + - `"scim.disabled"` - - `name: optional string` + - `"service_account.created"` - The name of the IP allowlist configuration. + - `"service_account.updated"` - - `"ip_allowlist.created": optional object { id, allowed_ips, name }` + - `"service_account.deleted"` - The details for events with this `type`. + - `"user.added"` - - `id: optional string` + - `"user.updated"` - The ID of the IP allowlist configuration. + - `"user.deleted"` - - `allowed_ips: optional array of string` + - `"tenant.metadata.updated"` - The IP addresses or CIDR ranges included in the configuration. + - `"tenant.microsoft_entra_mapping.upserted"` - - `name: optional string` + - `"tenant.microsoft_entra_mapping.deleted"` - The name of the IP allowlist configuration. + - `"tenant.workload_identity.provider.created"` - - `"ip_allowlist.deleted": optional object { id, allowed_ips, name }` + - `"tenant.workload_identity.provider.updated"` - The details for events with this `type`. + - `"tenant.workload_identity.provider.archived"` - - `id: optional string` + - `"tenant.workload_identity.mapping.created"` - The ID of the IP allowlist configuration. + - `"tenant.workload_identity.mapping.updated"` - - `allowed_ips: optional array of string` + - `"tenant.workload_identity.mapping.archived"` - The IP addresses or CIDR ranges that were in the configuration. + - `"tenant.workload_identity.binding.created"` - - `name: optional string` + - `"tenant.workload_identity.principal.provisioned"` - The name of the IP allowlist configuration. + - `"tenant.admin_api_key.created"` - - `"ip_allowlist.updated": optional object { id, allowed_ips }` + - `"tenant.admin_api_key.updated"` - The details for events with this `type`. + - `"tenant.admin_api_key.deleted"` - - `id: optional string` + - `"tenant.project_api_key.created"` - The ID of the IP allowlist configuration. + - `"tenant.chatgpt_access_token.revoked"` - - `allowed_ips: optional array of string` + - `"tenant.migration.completed"` - The updated set of IP addresses or CIDR ranges in the configuration. + - `"tenant.sso.migrated"` - - `"login.failed": optional object { error_code, error_message }` + - `"tenant.domains.migrated"` - The details for events with this `type`. + - `"tenant.sso_connection.created"` - - `error_code: optional string` + - `"tenant.sso_connection.updated"` - The error code of the failure. + - `"tenant.sso_connection.deleted"` - - `error_message: optional string` + - `"tenant.sso_connection.setup.started"` - The error message of the failure. + - `"tenant.policy.created"` - - `"login.succeeded": optional unknown` + - `"tenant.policy.updated"` - This event has no additional fields beyond the standard audit log attributes. + - `"tenant.policy.deleted"` - - `"logout.failed": optional object { error_code, error_message }` + - `"tenant.policy.attached"` - The details for events with this `type`. + - `"tenant.policy.detached"` - - `error_code: optional string` + - `"tenant.principal_authentication_policy.resolved"` - The error code of the failure. + - `"tenant.scim.setup.started"` - - `error_message: optional string` + - `"tenant.scim.deletion.requested"` - The error message of the failure. + - `"tenant.scim.directory.created"` - - `"logout.succeeded": optional unknown` + - `"tenant.product_access_policy.updated"` - This event has no additional fields beyond the standard audit log attributes. + - `"tenant.resource_share_grant.created"` - - `"organization.updated": optional object { id, changes_requested }` + - `"tenant.resource_share_grant.updated"` - The details for events with this `type`. + - `"tenant.resource_share_grant.accepted"` - - `id: optional string` + - `"tenant.resource_share_grant.declined"` - The organization ID. + - `"tenant.resource_share_grant.revoked"` - - `changes_requested: optional object { api_call_logging, api_call_logging_project_ids, description, 4 more }` + - `"tenant.resource_share_grant.deleted"` - The payload used to update the organization settings. + - `"tenant.service_account.updated"` - - `api_call_logging: optional string` + - `"tenant.service_account.deleted"` - How your organization logs data from supported API calls. One of `disabled`, `enabled_per_call`, `enabled_for_all_projects`, or `enabled_for_selected_projects` + - `"tenant.service_account.token.revoked"` - - `api_call_logging_project_ids: optional string` + - `"tenant.billing.overage_limit.updated"` - The list of project ids if api_call_logging is set to `enabled_for_selected_projects` + - `"tenant.billing.alerts.updated"` - - `description: optional string` + - `"tenant.billing.info.updated"` - The organization description. + - `"tenant.usage_limit.workspace.updated"` - - `name: optional string` + - `"tenant.usage_limit.group.updated"` - The organization name. + - `"tenant.usage_limit.user.updated"` - - `threads_ui_visibility: optional string` + - `"tenant.usage_limit.increase_request.updated"` - Visibility of the threads page which shows messages created with the Assistants API and Playground. One of `ANY_ROLE`, `OWNERS`, or `NONE`. + - `"tenant.usage_limit.increase_request.resolved"` - - `title: optional string` + - `"tenant.group.created"` - The organization title. + - `"tenant.group.updated"` - - `usage_dashboard_visibility: optional string` + - `"tenant.group.deleted"` - Visibility of the usage dashboard which shows activity and costs for your organization. One of `ANY_ROLE` or `OWNERS`. + - `"tenant.group.member.added"` - - `project: optional object { id, name }` + - `"tenant.group.member.removed"` - The project that the action was scoped to. Absent for actions not scoped to projects. Note that any admin actions taken via Admin API keys are associated with the default project. + - `"tenant.migration_rollout.status.updated"` - - `id: optional string` + - `"tenant.migration_rollout.tier.updated"` - The project ID. + - `"tenant.role.metadata.updated"` - - `name: optional string` + - `"tenant.custom_role.created"` - The project title. + - `"tenant.custom_role.updated"` - - `"project.archived": optional object { id }` + - `"tenant.custom_role.deleted"` - The details for events with this `type`. + - `"tenant.role_assignment.created"` - - `id: optional string` + - `"tenant.role_assignment.deleted"` - The project ID. + - `"tenant.resource_role_assignment.created"` - - `"project.created": optional object { id, data }` + - `"tenant.resource_role_assignment.deleted"` - The details for events with this `type`. + - `"tenant.resource_access.updated"` - - `id: optional string` + - `"tenant.resource_access.deleted"` - The project ID. + - `"tenant.session_policy.created"` - - `data: optional object { name, title }` + - `"tenant.session_policy.updated"` - The payload used to create the project. + - `"tenant.session_policy.deleted"` - - `name: optional string` + - `"tenant.session_revocation.started"` - The project name. + - `"tenant.third_party_app_policy.updated"` - - `title: optional string` + - `"tenant.user.added"` - The title of the project as seen on the dashboard. + - `"tenant.user.updated"` - - `"project.deleted": optional object { id }` + - `"tenant.user.removed"` - The details for events with this `type`. + - `"tenant.user.looked_up"` - - `id: optional string` + - `"tenant.user.invited"` - The project ID. + - `"tenant.membership.revoked"` - - `"project.updated": optional object { id, changes_requested }` + - `"tenant.api_organization_invite.upserted"` - The details for events with this `type`. + - `"tenant.api_organization_invite.deleted"` - - `id: optional string` + - `"tenant.chatgpt_workspace_invite.upserted"` - The project ID. + - `"tenant.membership.accepted"` - - `changes_requested: optional object { title }` + - `"tenant.membership.declined"` - The payload used to update the project. + - `"tenant.workspace_invite_email_settings.updated"` - - `title: optional string` + - `actor: optional object { api_key, session, type }` - The title of the project as seen on the dashboard. + The actor who performed the audit logged action. - - `"rate_limit.deleted": optional object { id }` + - `api_key: optional object { id, service_account, type, user }` - The details for events with this `type`. + The API Key used to perform the audit logged action. - `id: optional string` - The rate limit ID + The tracking id of the API key. - - `"rate_limit.updated": optional object { id, changes_requested }` + - `service_account: optional object { id }` - The details for events with this `type`. + The service account that performed the audit logged action. - `id: optional string` - The rate limit ID + The service account id. - - `changes_requested: optional object { batch_1_day_max_input_tokens, max_audio_megabytes_per_1_minute, max_images_per_1_minute, 3 more }` + - `type: optional "user" or "service_account"` - The payload used to update the rate limits. + The type of API key. Can be either `user` or `service_account`. - - `batch_1_day_max_input_tokens: optional number` + - `"user"` - The maximum batch input tokens per day. Only relevant for certain models. + - `"service_account"` - - `max_audio_megabytes_per_1_minute: optional number` + - `user: optional object { id, email }` - The maximum audio megabytes per minute. Only relevant for certain models. + The user who performed the audit logged action. - - `max_images_per_1_minute: optional number` + - `id: optional string` - The maximum images per minute. Only relevant for certain models. + The user id. - - `max_requests_per_1_day: optional number` + - `email: optional string` - The maximum requests per day. Only relevant for certain models. + The user email. - - `max_requests_per_1_minute: optional number` + - `session: optional object { ip_address, user }` - The maximum requests per minute. + The session in which the audit logged action was performed. - - `max_tokens_per_1_minute: optional number` + - `ip_address: optional string` - The maximum tokens per minute. + The IP address from which the action was performed. - - `"role.assignment.created": optional object { id, principal_id, principal_type, 2 more }` + - `user: optional object { id, email }` - The details for events with this `type`. + The user who performed the audit logged action. - `id: optional string` - The identifier of the role assignment. - - - `principal_id: optional string` - - The principal (user or group) that received the role. + The user id. - - `principal_type: optional string` + - `email: optional string` - The type of principal (user or group) that received the role. + The user email. - - `resource_id: optional string` + - `type: optional "session" or "api_key"` - The resource the role assignment is scoped to. + The type of actor. Is either `session` or `api_key`. - - `resource_type: optional string` + - `"session"` - The type of resource the role assignment is scoped to. + - `"api_key"` - - `"role.assignment.deleted": optional object { id, principal_id, principal_type, 2 more }` + - `"api_key.created": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The identifier of the role assignment. - - - `principal_id: optional string` - - The principal (user or group) that had the role removed. - - - `principal_type: optional string` - - The type of principal (user or group) that had the role removed. + The tracking ID of the API key. - - `resource_id: optional string` + - `data: optional object { scopes }` - The resource the role assignment was scoped to. + The payload used to create the API key. - - `resource_type: optional string` + - `scopes: optional array of string` - The type of resource the role assignment was scoped to. + A list of scopes allowed for the API key, e.g. `["api.model.request"]` - - `"role.bound_to_resource": optional object { id, connector_id, connector_name, 7 more }` + - `"api_key.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The ID of the resource the role was bound to. ChatGPT workspace connector resources use `__`. - - - `connector_id: optional string` + The tracking ID of the API key. - The connector ID for a ChatGPT workspace connector resource. + - `"api_key.updated": optional object { id, changes_requested }` - - `connector_name: optional string` + The details for events with this `type`. - The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. + - `id: optional string` - - `enabled: optional boolean` + The tracking ID of the API key. - Whether the connector is enabled for the role. + - `changes_requested: optional object { scopes }` - - `permissions: optional array of string` + The payload used to update the API key. - The permissions granted to the role for the resource. + - `scopes: optional array of string` - - `resource_id: optional string` + A list of scopes allowed for the API key, e.g. `["api.model.request"]` - The ID of the resource the role was bound to. + - `"certificate.created": optional object { id, name }` - - `resource_type: optional string` + The details for events with this `type`. - The type of resource the role was bound to. + - `id: optional string` - - `role_id: optional string` + The certificate ID. - The ID of the role that was bound to the resource. + - `name: optional string` - - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` + The name of the certificate. - The connector role mutation path that produced the event. + - `"certificate.deleted": optional object { id, certificate, name }` - - `"role_toggle"` + The details for events with this `type`. - - `"role_connector_update"` + - `id: optional string` - - `"role_delete"` + The certificate ID. - - `"workspace_permissions"` + - `certificate: optional string` - - `"connector_publish"` + The certificate content in PEM format. - - `workspace_id: optional string` + - `name: optional string` - The workspace ID for a ChatGPT workspace connector resource. + The name of the certificate. - - `"role.created": optional object { id, permissions, resource_id, 2 more }` + - `"certificate.updated": optional object { id, name }` The details for events with this `type`. - `id: optional string` - The role ID. + The certificate ID. - - `permissions: optional array of string` + - `name: optional string` - The permissions granted by the role. + The name of the certificate. - - `resource_id: optional string` + - `"certificates.activated": optional object { certificates }` - The resource the role is scoped to. + The details for events with this `type`. - - `resource_type: optional string` + - `certificates: optional array of object { id, name }` - The type of resource the role belongs to. + - `id: optional string` - - `role_name: optional string` + The certificate ID. - The name of the role. + - `name: optional string` - - `"role.deleted": optional object { id }` + The name of the certificate. + + - `"certificates.deactivated": optional object { certificates }` The details for events with this `type`. - - `id: optional string` + - `certificates: optional array of object { id, name }` - The role ID. + - `id: optional string` - - `"role.unbound_from_resource": optional object { id, connector_id, connector_name, 7 more }` + The certificate ID. - The details for events with this `type`. + - `name: optional string` - - `id: optional string` + The name of the certificate. - The ID of the resource the role was unbound from. ChatGPT workspace connector resources use `__`. + - `"checkpoint.permission.created": optional object { id, data }` - - `connector_id: optional string` + The project and fine-tuned model checkpoint that the checkpoint permission was created for. - The connector ID for a ChatGPT workspace connector resource. + - `id: optional string` - - `connector_name: optional string` + The ID of the checkpoint permission. - The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. + - `data: optional object { fine_tuned_model_checkpoint, project_id }` - - `enabled: optional boolean` + The payload used to create the checkpoint permission. - Whether the connector is enabled for the role. + - `fine_tuned_model_checkpoint: optional string` - - `permissions: optional array of string` + The ID of the fine-tuned model checkpoint. - The permissions remaining for the role after the change. + - `project_id: optional string` - - `resource_id: optional string` + The ID of the project that the checkpoint permission was created for. - The ID of the resource the role was unbound from. + - `"checkpoint.permission.deleted": optional object { id }` - - `resource_type: optional string` + The details for events with this `type`. - The type of resource the role was unbound from. + - `id: optional string` - - `role_id: optional string` + The ID of the checkpoint permission. - The ID of the role that was unbound from the resource. + - `"external_key.registered": optional object { id, data }` - - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` + The details for events with this `type`. - The connector role mutation path that produced the event. + - `id: optional string` - - `"role_toggle"` + The ID of the external key configuration. - - `"role_connector_update"` + - `data: optional unknown` - - `"role_delete"` + The configuration for the external key. - - `"workspace_permissions"` + - `"external_key.removed": optional object { id }` - - `"connector_publish"` + The details for events with this `type`. - - `workspace_id: optional string` + - `id: optional string` - The workspace ID for a ChatGPT workspace connector resource. + The ID of the external key configuration. - - `"role.updated": optional object { id, changes_requested }` + - `"group.created": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The role ID. + The ID of the group. - - `changes_requested: optional object { description, metadata, permissions_added, 4 more }` + - `data: optional object { group_name }` - The payload used to update the role. + Information about the created group. - - `description: optional string` + - `group_name: optional string` - The updated role description, when provided. + The group name. - - `metadata: optional unknown` + - `"group.deleted": optional object { id }` - Additional metadata stored on the role. + The details for events with this `type`. - - `permissions_added: optional array of string` + - `id: optional string` - The permissions added to the role. + The ID of the group. - - `permissions_removed: optional array of string` + - `"group.updated": optional object { id, changes_requested }` - The permissions removed from the role. + The details for events with this `type`. - - `resource_id: optional string` + - `id: optional string` - The resource the role is scoped to. + The ID of the group. - - `resource_type: optional string` + - `changes_requested: optional object { group_name }` - The type of resource the role belongs to. + The payload used to update the group. - - `role_name: optional string` + - `group_name: optional string` - The updated role name, when provided. + The updated group name. - - `"scim.disabled": optional object { id }` + - `"invite.accepted": optional object { id }` The details for events with this `type`. - `id: optional string` - The ID of the SCIM was disabled for. + The ID of the invite. - - `"scim.enabled": optional object { id }` + - `"invite.deleted": optional object { id }` The details for events with this `type`. - `id: optional string` - The ID of the SCIM was enabled for. + The ID of the invite. - - `"service_account.created": optional object { id, data }` + - `"invite.sent": optional object { id, data }` The details for events with this `type`. - `id: optional string` - The service account ID. + The ID of the invite. - - `data: optional object { role }` + - `data: optional object { email, role }` - The payload used to create the service account. + The payload used to create the invite. + + - `email: optional string` + + The email invited to the organization. - `role: optional string` - The role of the service account. Is either `owner` or `member`. + The role the email was invited to be. Is either `owner` or `member`. - - `"service_account.deleted": optional object { id }` + - `"ip_allowlist.config.activated": optional object { configs }` The details for events with this `type`. + - `configs: optional array of object { id, name }` + + The configurations that were activated. + - `id: optional string` - The service account ID. + The ID of the IP allowlist configuration. - - `"service_account.updated": optional object { id, changes_requested }` + - `name: optional string` + + The name of the IP allowlist configuration. + + - `"ip_allowlist.config.deactivated": optional object { configs }` The details for events with this `type`. - - `id: optional string` + - `configs: optional array of object { id, name }` - The service account ID. + The configurations that were deactivated. - - `changes_requested: optional object { role }` + - `id: optional string` - The payload used to updated the service account. + The ID of the IP allowlist configuration. - - `role: optional string` + - `name: optional string` - The role of the service account. Is either `owner` or `member`. + The name of the IP allowlist configuration. - - `"user.added": optional object { id, data }` + - `"ip_allowlist.created": optional object { id, allowed_ips, name }` The details for events with this `type`. - `id: optional string` - The user ID. + The ID of the IP allowlist configuration. - - `data: optional object { role }` + - `allowed_ips: optional array of string` - The payload used to add the user to the project. + The IP addresses or CIDR ranges included in the configuration. - - `role: optional string` + - `name: optional string` - The role of the user. Is either `owner` or `member`. + The name of the IP allowlist configuration. - - `"user.deleted": optional object { id }` + - `"ip_allowlist.deleted": optional object { id, allowed_ips, name }` The details for events with this `type`. - `id: optional string` - The user ID. + The ID of the IP allowlist configuration. - - `"user.updated": optional object { id, changes_requested }` + - `allowed_ips: optional array of string` - The details for events with this `type`. + The IP addresses or CIDR ranges that were in the configuration. - - `id: optional string` + - `name: optional string` - The project ID. + The name of the IP allowlist configuration. - - `changes_requested: optional object { role }` + - `"ip_allowlist.updated": optional object { id, allowed_ips }` - The payload used to update the user. + The details for events with this `type`. - - `role: optional string` + - `id: optional string` - The role of the user. Is either `owner` or `member`. + The ID of the IP allowlist configuration. - - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }` + - `allowed_ips: optional array of string` - The details for events with this `type`. + The updated set of IP addresses or CIDR ranges in the configuration. - - `id: optional string` + - `"login.failed": optional object { error_code, error_message }` - The workload identity provider mapping ID. + The details for events with this `type`. - - `data: optional unknown` + - `error_code: optional string` - The payload used to create the workload identity provider mapping. + The error code of the failure. - - `identity_provider_id: optional string` + - `error_message: optional string` - The workload identity provider ID. + The error message of the failure. - - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }` + - `"login.succeeded": optional unknown` - The details for events with this `type`. + This event has no additional fields beyond the standard audit log attributes. - - `id: optional string` + - `"logout.failed": optional object { error_code, error_message }` - The workload identity provider mapping ID. + The details for events with this `type`. - - `identity_provider_id: optional string` + - `error_code: optional string` - The workload identity provider ID. + The error code of the failure. - - `project_id: optional string` + - `error_message: optional string` - The project ID. + The error message of the failure. - - `service_account_id: optional string` + - `"logout.succeeded": optional unknown` - The mapped service account ID. + This event has no additional fields beyond the standard audit log attributes. - - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }` + - `"organization.updated": optional object { id, changes_requested }` The details for events with this `type`. - `id: optional string` - The workload identity provider mapping ID. + The organization ID. - - `changes_requested: optional unknown` + - `changes_requested: optional object { api_call_logging, api_call_logging_project_ids, description, 4 more }` - The payload used to update the workload identity provider mapping. + The payload used to update the organization settings. - - `identity_provider_id: optional string` + - `api_call_logging: optional string` - The workload identity provider ID. + How your organization logs data from supported API calls. One of `disabled`, `enabled_per_call`, `enabled_for_all_projects`, or `enabled_for_selected_projects` - - `"workload_identity_provider.created": optional object { id, data }` + - `api_call_logging_project_ids: optional string` - The details for events with this `type`. + The list of project ids if api_call_logging is set to `enabled_for_selected_projects` - - `id: optional string` + - `description: optional string` - The workload identity provider ID. + The organization description. - - `data: optional unknown` + - `name: optional string` - The payload used to create the workload identity provider. + The organization name. - - `"workload_identity_provider.deleted": optional object { id, name }` + - `threads_ui_visibility: optional string` - The details for events with this `type`. + Visibility of the threads page which shows messages created with the Assistants API and Playground. One of `ANY_ROLE`, `OWNERS`, or `NONE`. - - `id: optional string` + - `title: optional string` - The workload identity provider ID. + The organization title. - - `name: optional string` + - `usage_dashboard_visibility: optional string` - The workload identity provider name. + Visibility of the usage dashboard which shows activity and costs for your organization. One of `ANY_ROLE` or `OWNERS`. - - `"workload_identity_provider.updated": optional object { id, changes_requested }` + - `project: optional object { id, name }` - The details for events with this `type`. + The project that the action was scoped to. Absent for actions not scoped to projects. Note that any admin actions taken via Admin API keys are associated with the default project. - `id: optional string` - The workload identity provider ID. + The project ID. - - `changes_requested: optional unknown` + - `name: optional string` - The payload used to update the workload identity provider. + The project title. -# Admin API Keys + - `"project.archived": optional object { id }` -## List all organization and project API keys. + The details for events with this `type`. -**get** `/organization/admin_api_keys` + - `id: optional string` -List organization API keys + The project ID. -### Query Parameters + - `"project.created": optional object { id, data }` -- `after: optional string` + The details for events with this `type`. - Return keys with IDs that come after this ID in the pagination order. + - `id: optional string` -- `limit: optional number` + The project ID. - Maximum number of keys to return. + - `data: optional object { name, title }` -- `order: optional "asc" or "desc"` + The payload used to create the project. - Order results by creation time, ascending or descending. + - `name: optional string` - - `"asc"` + The project name. - - `"desc"` + - `title: optional string` -### Returns + The title of the project as seen on the dashboard. -- `data: array of AdminAPIKey` + - `"project.deleted": optional object { id }` - - `id: string` + The details for events with this `type`. - The identifier, which can be referenced in API endpoints + - `id: optional string` - - `created_at: number` + The project ID. - The Unix timestamp (in seconds) of when the API key was created + - `"project.updated": optional object { id, changes_requested }` - - `expires_at: number` + The details for events with this `type`. - The Unix timestamp (in seconds) of when the API key expires + - `id: optional string` - - `object: "organization.admin_api_key"` + The project ID. - The object type, which is always `organization.admin_api_key` + - `changes_requested: optional object { title }` - - `"organization.admin_api_key"` + The payload used to update the project. - - `owner: object { id, created_at, name, 3 more }` + - `title: optional string` - - `id: optional string` + The title of the project as seen on the dashboard. - The identifier, which can be referenced in API endpoints + - `"rate_limit.deleted": optional object { id }` - - `created_at: optional number` + The details for events with this `type`. - The Unix timestamp (in seconds) of when the user was created + - `id: optional string` - - `name: optional string` + The rate limit ID - The name of the user + - `"rate_limit.updated": optional object { id, changes_requested }` - - `object: optional string` + The details for events with this `type`. - The object type, which is always organization.user + - `id: optional string` - - `role: optional string` + The rate limit ID - Always `owner` + - `changes_requested: optional object { batch_1_day_max_input_tokens, max_audio_megabytes_per_1_minute, max_images_per_1_minute, 3 more }` - - `type: optional string` + The payload used to update the rate limits. - Always `user` + - `batch_1_day_max_input_tokens: optional number` - - `redacted_value: string` + The maximum batch input tokens per day. Only relevant for certain models. - The redacted value of the API key + - `max_audio_megabytes_per_1_minute: optional number` - - `last_used_at: optional number` + The maximum audio megabytes per minute. Only relevant for certain models. - The Unix timestamp (in seconds) of when the API key was last used + - `max_images_per_1_minute: optional number` - - `name: optional string` + The maximum images per minute. Only relevant for certain models. - The name of the API key + - `max_requests_per_1_day: optional number` -- `has_more: boolean` + The maximum requests per day. Only relevant for certain models. -- `object: "list"` + - `max_requests_per_1_minute: optional number` - - `"list"` + The maximum requests per minute. -- `first_id: optional string` + - `max_tokens_per_1_minute: optional number` -- `last_id: optional string` + The maximum tokens per minute. -### Example + - `"role.assignment.created": optional object { id, principal_id, principal_type, 2 more }` -```http -curl https://api.openai.com/v1/organization/admin_api_keys \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The details for events with this `type`. -#### Response + - `id: optional string` -```json -{ - "data": [ - { - "id": "key_abc", - "created_at": 1711471533, - "expires_at": 1714063533, - "object": "organization.admin_api_key", - "owner": { - "id": "sa_456", - "created_at": 1711471533, - "name": "My Service Account", - "object": "organization.user", - "role": "owner", - "type": "user" - }, - "redacted_value": "sk-admin...def", - "last_used_at": 1711471534, - "name": "Administration Key" - } - ], - "has_more": false, - "object": "list", - "first_id": "key_abc", - "last_id": "key_xyz" -} -``` + The identifier of the role assignment. -### Example + - `principal_id: optional string` -```http -curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The principal (user or group) that received the role. -#### Response + - `principal_type: optional string` -```json -{ - "object": "list", - "data": [ - { - "object": "organization.admin_api_key", - "id": "key_abc", - "name": "Main Admin Key", - "redacted_value": "sk-admin...def", - "created_at": 1711471533, - "expires_at": 1714063533, - "last_used_at": 1711471534, - "owner": { - "type": "service_account", - "object": "organization.service_account", - "id": "sa_456", - "name": "My Service Account", - "created_at": 1711471533, - "role": "member" - } - } - ], - "first_id": "key_abc", - "last_id": "key_abc", - "has_more": false -} -``` + The type of principal (user or group) that received the role. -## Create admin API key + - `resource_id: optional string` -**post** `/organization/admin_api_keys` + The resource the role assignment is scoped to. -Create an organization admin API key + - `resource_type: optional string` -### Body Parameters + The type of resource the role assignment is scoped to. -- `name: string` + - `"role.assignment.deleted": optional object { id, principal_id, principal_type, 2 more }` -- `expires_in_seconds: optional number` + The details for events with this `type`. - The number of seconds until the API key expires. Omit this field for a key that does not expire. + - `id: optional string` -### Returns + The identifier of the role assignment. -- `value: string` + - `principal_id: optional string` - The value of the API key. Only shown on create. + The principal (user or group) that had the role removed. -### Example + - `principal_type: optional string` -```http -curl https://api.openai.com/v1/organization/admin_api_keys \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "name": "New Admin Key", - "expires_in_seconds": 2592000 - }' -``` + The type of principal (user or group) that had the role removed. -#### Response + - `resource_id: optional string` -```json -{ - "id": "key_abc", - "created_at": 1711471533, - "expires_at": 1714063533, - "object": "organization.admin_api_key", - "owner": { - "id": "sa_456", - "created_at": 1711471533, - "name": "My Service Account", - "object": "organization.user", - "role": "owner", - "type": "user" - }, - "redacted_value": "sk-admin...def", - "last_used_at": 1711471534, - "name": "Administration Key", - "value": "sk-admin-1234abcd" -} -``` + The resource the role assignment was scoped to. -### Example + - `resource_type: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/admin_api_keys \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "New Admin Key", - "expires_in_seconds": 2592000 - }' -``` + The type of resource the role assignment was scoped to. -#### Response + - `"role.bound_to_resource": optional object { id, connector_id, connector_name, 7 more }` -```json -{ - "object": "organization.admin_api_key", - "id": "key_xyz", - "name": "New Admin Key", - "redacted_value": "sk-admin...xyz", - "created_at": 1711471533, - "expires_at": 1714063533, - "last_used_at": 1711471534, - "owner": { - "type": "user", - "object": "organization.user", - "id": "user_123", - "name": "John Doe", - "created_at": 1711471533, - "role": "owner" - }, - "value": "sk-admin-1234abcd" -} -``` + The details for events with this `type`. -## Retrieve admin API key + - `id: optional string` -**get** `/organization/admin_api_keys/{key_id}` + The ID of the resource the role was bound to. ChatGPT workspace connector resources use `__`. -Retrieve a single organization API key + - `connector_id: optional string` -### Path Parameters + The connector ID for a ChatGPT workspace connector resource. -- `key_id: string` + - `connector_name: optional string` - The ID of the API key. + The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. -### Returns + - `enabled: optional boolean` -- `AdminAPIKey object { id, created_at, expires_at, 5 more }` + Whether the connector is enabled for the role. - Represents an individual Admin API key in an org. + - `permissions: optional array of string` - - `id: string` + The permissions granted to the role for the resource. - The identifier, which can be referenced in API endpoints + - `resource_id: optional string` - - `created_at: number` + The ID of the resource the role was bound to. - The Unix timestamp (in seconds) of when the API key was created + - `resource_type: optional string` - - `expires_at: number` + The type of resource the role was bound to. - The Unix timestamp (in seconds) of when the API key expires + - `role_id: optional string` - - `object: "organization.admin_api_key"` + The ID of the role that was bound to the resource. - The object type, which is always `organization.admin_api_key` + - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` - - `"organization.admin_api_key"` + The connector role mutation path that produced the event. - - `owner: object { id, created_at, name, 3 more }` + - `"role_toggle"` - - `id: optional string` + - `"role_connector_update"` - The identifier, which can be referenced in API endpoints + - `"role_delete"` - - `created_at: optional number` + - `"workspace_permissions"` - The Unix timestamp (in seconds) of when the user was created + - `"connector_publish"` - - `name: optional string` + - `workspace_id: optional string` - The name of the user + The workspace ID for a ChatGPT workspace connector resource. - - `object: optional string` + - `"role.created": optional object { id, permissions, resource_id, 2 more }` - The object type, which is always organization.user + The details for events with this `type`. - - `role: optional string` + - `id: optional string` - Always `owner` + The role ID. - - `type: optional string` + - `permissions: optional array of string` - Always `user` + The permissions granted by the role. - - `redacted_value: string` + - `resource_id: optional string` - The redacted value of the API key + The resource the role is scoped to. - - `last_used_at: optional number` + - `resource_type: optional string` - The Unix timestamp (in seconds) of when the API key was last used + The type of resource the role belongs to. - - `name: optional string` + - `role_name: optional string` - The name of the API key + The name of the role. -### Example + - `"role.deleted": optional object { id }` -```http -curl https://api.openai.com/v1/organization/admin_api_keys/$KEY_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The details for events with this `type`. -#### Response + - `id: optional string` -```json -{ - "id": "key_abc", - "created_at": 1711471533, - "expires_at": 1714063533, - "object": "organization.admin_api_key", - "owner": { - "id": "sa_456", - "created_at": 1711471533, - "name": "My Service Account", - "object": "organization.user", - "role": "owner", - "type": "user" - }, - "redacted_value": "sk-admin...def", - "last_used_at": 1711471534, - "name": "Administration Key" -} -``` + The role ID. -### Example + - `"role.unbound_from_resource": optional object { id, connector_id, connector_name, 7 more }` -```http -curl https://api.openai.com/v1/organization/admin_api_keys/key_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The details for events with this `type`. -#### Response + - `id: optional string` -```json -{ - "object": "organization.admin_api_key", - "id": "key_abc", - "name": "Main Admin Key", - "redacted_value": "sk-admin...xyz", - "created_at": 1711471533, - "last_used_at": 1711471534, - "owner": { - "type": "user", - "object": "organization.user", - "id": "user_123", - "name": "John Doe", - "created_at": 1711471533, - "role": "owner" - } -} -``` + The ID of the resource the role was unbound from. ChatGPT workspace connector resources use `__`. -## Delete admin API key + - `connector_id: optional string` -**delete** `/organization/admin_api_keys/{key_id}` + The connector ID for a ChatGPT workspace connector resource. -Delete an organization admin API key + - `connector_name: optional string` -### Path Parameters + The connector display name for a ChatGPT workspace connector resource, or the connector ID when the display name could not be resolved. -- `key_id: string` + - `enabled: optional boolean` - The ID of the API key to be deleted. + Whether the connector is enabled for the role. -### Returns + - `permissions: optional array of string` -- `id: string` + The permissions remaining for the role after the change. -- `deleted: boolean` + - `resource_id: optional string` -- `object: "organization.admin_api_key.deleted"` + The ID of the resource the role was unbound from. - - `"organization.admin_api_key.deleted"` + - `resource_type: optional string` -### Example + The type of resource the role was unbound from. -```http -curl https://api.openai.com/v1/organization/admin_api_keys/$KEY_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `role_id: optional string` -#### Response + The ID of the role that was unbound from the resource. -```json -{ - "id": "key_abc", - "deleted": true, - "object": "organization.admin_api_key.deleted" -} -``` + - `source: optional "role_toggle" or "role_connector_update" or "role_delete" or 2 more` -### Example + The connector role mutation path that produced the event. -```http -curl -X DELETE https://api.openai.com/v1/organization/admin_api_keys/key_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `"role_toggle"` -#### Response + - `"role_connector_update"` -```json -{ - "id": "key_abc", - "object": "organization.admin_api_key.deleted", - "deleted": true -} -``` + - `"role_delete"` -## Domain Types + - `"workspace_permissions"` -### Admin API Key + - `"connector_publish"` -- `AdminAPIKey object { id, created_at, expires_at, 5 more }` + - `workspace_id: optional string` - Represents an individual Admin API key in an org. + The workspace ID for a ChatGPT workspace connector resource. - - `id: string` + - `"role.updated": optional object { id, changes_requested }` - The identifier, which can be referenced in API endpoints + The details for events with this `type`. - - `created_at: number` + - `id: optional string` - The Unix timestamp (in seconds) of when the API key was created + The role ID. - - `expires_at: number` + - `changes_requested: optional object { description, metadata, permissions_added, 4 more }` - The Unix timestamp (in seconds) of when the API key expires + The payload used to update the role. - - `object: "organization.admin_api_key"` + - `description: optional string` - The object type, which is always `organization.admin_api_key` + The updated role description, when provided. - - `"organization.admin_api_key"` + - `metadata: optional unknown` - - `owner: object { id, created_at, name, 3 more }` + Additional metadata stored on the role. - - `id: optional string` + - `permissions_added: optional array of string` - The identifier, which can be referenced in API endpoints + The permissions added to the role. - - `created_at: optional number` + - `permissions_removed: optional array of string` - The Unix timestamp (in seconds) of when the user was created + The permissions removed from the role. - - `name: optional string` + - `resource_id: optional string` - The name of the user + The resource the role is scoped to. - - `object: optional string` + - `resource_type: optional string` - The object type, which is always organization.user + The type of resource the role belongs to. - - `role: optional string` + - `role_name: optional string` - Always `owner` + The updated role name, when provided. - - `type: optional string` + - `"scim.disabled": optional object { id }` - Always `user` + The details for events with this `type`. - - `redacted_value: string` + - `id: optional string` - The redacted value of the API key + The ID of the SCIM was disabled for. - - `last_used_at: optional number` + - `"scim.enabled": optional object { id }` - The Unix timestamp (in seconds) of when the API key was last used + The details for events with this `type`. - - `name: optional string` + - `id: optional string` - The name of the API key + The ID of the SCIM was enabled for. -### Admin API Key Create Response + - `"service_account.created": optional object { id, data }` -- `AdminAPIKeyCreateResponse = AdminAPIKey` + The details for events with this `type`. - Represents an individual Admin API key in an org. + - `id: optional string` - - `value: string` + The service account ID. - The value of the API key. Only shown on create. + - `data: optional object { role }` -### Admin API Key Delete Response + The payload used to create the service account. -- `AdminAPIKeyDeleteResponse object { id, deleted, object }` + - `role: optional string` - - `id: string` + The role of the service account. Is either `owner` or `member`. - - `deleted: boolean` + - `"service_account.deleted": optional object { id }` - - `object: "organization.admin_api_key.deleted"` + The details for events with this `type`. - - `"organization.admin_api_key.deleted"` + - `id: optional string` -# Usage + The service account ID. -## Audio speeches + - `"service_account.updated": optional object { id, changes_requested }` -**get** `/organization/usage/audio_speeches` + The details for events with this `type`. -Get audio speeches usage details for the organization. + - `id: optional string` -### Query Parameters + The service account ID. -- `start_time: number` + - `changes_requested: optional object { role }` - Start time (Unix seconds) of the query time range, inclusive. + The payload used to updated the service account. -- `api_key_ids: optional array of string` + - `role: optional string` - Return only usage for these API keys. + The role of the service account. Is either `owner` or `member`. -- `bucket_width: optional "1m" or "1h" or "1d"` + - `"user.added": optional object { id, data }` - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + The details for events with this `type`. - - `"1m"` + - `id: optional string` - - `"1h"` + The user ID. - - `"1d"` + - `data: optional object { role }` -- `end_time: optional number` + The payload used to add the user to the project. - End time (Unix seconds) of the query time range, exclusive. + - `role: optional string` -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` + The role of the user. Is either `owner` or `member`. - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. + - `"user.deleted": optional object { id }` - - `"project_id"` + The details for events with this `type`. - - `"user_id"` + - `id: optional string` - - `"api_key_id"` + The user ID. - - `"model"` + - `"user.updated": optional object { id, changes_requested }` -- `limit: optional number` + The details for events with this `type`. - Specifies the number of buckets to return. + - `id: optional string` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + The project ID. -- `models: optional array of string` + - `changes_requested: optional object { role }` - Return only usage for these models. + The payload used to update the user. -- `page: optional string` + - `role: optional string` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + The role of the user. Is either `owner` or `member`. -- `project_ids: optional array of string` + - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }` - Return only usage for these projects. + The details for events with this `type`. -- `user_ids: optional array of string` + - `id: optional string` - Return only usage for these users. + The workload identity provider mapping ID. -### Returns + - `data: optional unknown` -- `data: array of object { end_time, object, results, start_time }` + The payload used to create the workload identity provider mapping. - - `end_time: number` + - `identity_provider_id: optional string` - - `object: "bucket"` + The workload identity provider ID. - - `"bucket"` + - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + The details for events with this `type`. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `id: optional string` - The aggregated completions usage details of the specific time bucket. + The workload identity provider mapping ID. - - `input_tokens: number` + - `identity_provider_id: optional string` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The workload identity provider ID. - - `num_model_requests: number` + - `project_id: optional string` - The count of requests made to the model. + The project ID. - - `object: "organization.usage.completions.result"` + - `service_account_id: optional string` - - `"organization.usage.completions.result"` + The mapped service account ID. - - `output_tokens: number` + - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The details for events with this `type`. - - `api_key_id: optional string` + - `id: optional string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The workload identity provider mapping ID. - - `batch: optional boolean` + - `changes_requested: optional unknown` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + The payload used to update the workload identity provider mapping. - - `input_audio_tokens: optional number` + - `identity_provider_id: optional string` - The aggregated number of uncached audio input tokens used. + The workload identity provider ID. - - `input_cache_write_tokens: optional number` + - `"workload_identity_provider.created": optional object { id, data }` - The aggregated number of input tokens written to the cache. + The details for events with this `type`. - - `input_cached_audio_tokens: optional number` + - `id: optional string` - The aggregated number of cached audio input tokens used. + The workload identity provider ID. - - `input_cached_image_tokens: optional number` + - `data: optional unknown` - The aggregated number of cached image input tokens used. + The payload used to create the workload identity provider. - - `input_cached_text_tokens: optional number` + - `"workload_identity_provider.deleted": optional object { id, name }` - The aggregated number of cached text input tokens used. + The details for events with this `type`. - - `input_cached_tokens: optional number` + - `id: optional string` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The workload identity provider ID. - - `input_image_tokens: optional number` + - `name: optional string` - The aggregated number of uncached image input tokens used. + The workload identity provider name. - - `input_text_tokens: optional number` + - `"workload_identity_provider.updated": optional object { id, changes_requested }` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + The details for events with this `type`. - - `input_uncached_tokens: optional number` + - `id: optional string` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + The workload identity provider ID. - - `model: optional string` + - `changes_requested: optional unknown` - When `group_by=model`, this field provides the model name of the grouped usage result. + The payload used to update the workload identity provider. - - `output_audio_tokens: optional number` +# Certificates - The aggregated number of audio output tokens used. +## Activate certificates for organization - - `output_image_tokens: optional number` +**post** `/organization/certificates/activate` - The aggregated number of image output tokens used. +Activate certificates at the organization level. - - `output_text_tokens: optional number` +You can atomically and idempotently activate up to 10 certificates at a time. - The aggregated number of text output tokens used. +### Body Parameters - - `project_id: optional string` +- `certificate_ids: array of string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Returns - - `service_tier: optional string` +- `data: array of object { id, active, certificate_details, 3 more }` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `id: string` - - `user_id: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `active: boolean` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + Whether the certificate is currently active at the organization level. - The aggregated embeddings usage details of the specific time bucket. + - `certificate_details: object { expires_at, valid_at }` - - `input_tokens: number` + - `expires_at: optional number` - The aggregated number of input tokens used. + The Unix timestamp (in seconds) of when the certificate expires. - - `num_model_requests: number` + - `valid_at: optional number` - The count of requests made to the model. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `object: "organization.usage.embeddings.result"` + - `created_at: number` - - `"organization.usage.embeddings.result"` + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `api_key_id: optional string` + - `name: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The name of the certificate. - - `model: optional string` + - `object: "organization.certificate"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The object type, which is always `organization.certificate`. - - `project_id: optional string` + - `"organization.certificate"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `object: "organization.certificate.activation"` - - `user_id: optional string` + The organization certificate activation result type. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"organization.certificate.activation"` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +### Example - The aggregated moderations usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/certificates/activate \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "certificate_ids": [ + "cert_abc" + ] + }' +``` - - `input_tokens: number` +#### Response - The aggregated number of input tokens used. +```json +{ + "data": [ + { + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.certificate" + } + ], + "object": "organization.certificate.activation" +} +``` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/certificates/activate \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "certificate_ids": ["cert_abc", "cert_def"] +}' +``` - - `object: "organization.usage.moderations.result"` +#### Response - - `"organization.usage.moderations.result"` +```json +{ + "object": "organization.certificate.activation", + "data": [ + { + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], +} +``` - - `api_key_id: optional string` +## Upload certificate - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +**post** `/organization/certificates` - - `model: optional string` +Upload a certificate to the organization. This does **not** automatically activate the certificate. - When `group_by=model`, this field provides the model name of the grouped usage result. +Organizations can upload up to 50 certificates. - - `project_id: optional string` +### Body Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `certificate: string` - - `user_id: optional string` + The certificate content in PEM format - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `name: optional string` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + An optional name for the certificate - The aggregated images usage details of the specific time bucket. +### Returns - - `images: number` +- `Certificate object { id, certificate_details, created_at, 3 more }` - The number of images processed. + Represents an individual `certificate` uploaded to the organization. - - `num_model_requests: number` + - `id: string` - The count of requests made to the model. + The identifier, which can be referenced in API endpoints - - `object: "organization.usage.images.result"` + - `certificate_details: object { content, expires_at, valid_at }` - - `"organization.usage.images.result"` + - `content: optional string` - - `api_key_id: optional string` + The content of the certificate in PEM format. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `expires_at: optional number` - - `model: optional string` + The Unix timestamp (in seconds) of when the certificate expires. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `valid_at: optional number` - - `project_id: optional string` + The Unix timestamp (in seconds) of when the certificate becomes valid. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `created_at: number` - - `size: optional string` + The Unix timestamp (in seconds) of when the certificate was uploaded. - When `group_by=size`, this field provides the image size of the grouped usage result. + - `name: string` - - `source: optional string` + The name of the certificate. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` - - `user_id: optional string` + The object type. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - If creating, updating, or getting a specific certificate, the object type is `certificate`. + - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. + - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `"certificate"` - The aggregated audio speeches usage details of the specific time bucket. + - `"organization.certificate"` - - `characters: number` + - `"organization.project.certificate"` - The number of characters processed. + - `active: optional boolean` - - `num_model_requests: number` + Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. - The count of requests made to the model. +### Example - - `object: "organization.usage.audio_speeches.result"` +```http +curl https://api.openai.com/v1/organization/certificates \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "certificate": "certificate" + }' +``` - - `"organization.usage.audio_speeches.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "id": "id", + "certificate_details": { + "content": "content", + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "certificate", + "active": true +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `model: optional string` +```http +curl -X POST https://api.openai.com/v1/organization/certificates \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "My Example Certificate", + "certificate": "-----BEGIN CERTIFICATE-----\\nMIIDeT...\\n-----END CERTIFICATE-----" +}' +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "object": "certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## Deactivate certificates for organization - - `user_id: optional string` +**post** `/organization/certificates/deactivate` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Deactivate certificates at the organization level. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +You can atomically and idempotently deactivate up to 10 certificates at a time. - The aggregated audio transcriptions usage details of the specific time bucket. +### Body Parameters - - `num_model_requests: number` +- `certificate_ids: array of string` - The count of requests made to the model. +### Returns - - `object: "organization.usage.audio_transcriptions.result"` +- `data: array of object { id, active, certificate_details, 3 more }` - - `"organization.usage.audio_transcriptions.result"` + - `id: string` - - `seconds: number` + The identifier, which can be referenced in API endpoints - The number of seconds processed. + - `active: boolean` - - `api_key_id: optional string` + Whether the certificate is currently active at the organization level. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `certificate_details: object { expires_at, valid_at }` - - `model: optional string` + - `expires_at: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate expires. - - `project_id: optional string` + - `valid_at: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `user_id: optional string` + - `created_at: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + - `name: string` - The aggregated vector stores usage details of the specific time bucket. + The name of the certificate. - - `object: "organization.usage.vector_stores.result"` + - `object: "organization.certificate"` - - `"organization.usage.vector_stores.result"` + The object type, which is always `organization.certificate`. - - `usage_bytes: number` + - `"organization.certificate"` - The vector stores usage in bytes. +- `object: "organization.certificate.deactivation"` - - `project_id: optional string` + The organization certificate deactivation result type. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.certificate.deactivation"` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +### Example - The aggregated code interpreter sessions usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/certificates/deactivate \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "certificate_ids": [ + "cert_abc" + ] + }' +``` - - `num_sessions: number` +#### Response - The number of code interpreter sessions. +```json +{ + "data": [ + { + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.certificate" + } + ], + "object": "organization.certificate.deactivation" +} +``` - - `object: "organization.usage.code_interpreter_sessions.result"` +### Example - - `"organization.usage.code_interpreter_sessions.result"` +```http +curl https://api.openai.com/v1/organization/certificates/deactivate \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "certificate_ids": ["cert_abc", "cert_def"] +}' +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```json +{ + "object": "organization.certificate.deactivation", + "data": [ + { + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], +} +``` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +## Delete certificate - The aggregated file search calls usage details of the specific time bucket. +**delete** `/organization/certificates/{certificate_id}` - - `num_requests: number` +Delete a certificate from the organization. - The count of file search calls. +The certificate must be inactive for the organization and all projects. - - `object: "organization.usage.file_searches.result"` +### Path Parameters - - `"organization.usage.file_searches.result"` +- `certificate_id: string` - - `api_key_id: optional string` +### Returns - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `id: string` - - `project_id: optional string` + The ID of the certificate that was deleted. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `object: "certificate.deleted"` - - `user_id: optional string` + The object type, must be `certificate.deleted`. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"certificate.deleted"` - - `vector_store_id: optional string` +### Example - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +#### Response - The aggregated web search calls usage details of the specific time bucket. +```json +{ + "id": "id", + "object": "certificate.deleted" +} +``` - - `num_model_requests: number` +### Example - The count of model requests. +```http +curl -X DELETE https://api.openai.com/v1/organization/certificates/cert_abc \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `num_requests: number` +#### Response - The count of web search calls. +```json +{ + "object": "certificate.deleted", + "id": "cert_abc" +} +``` - - `object: "organization.usage.web_searches.result"` +## List organization certificates - - `"organization.usage.web_searches.result"` +**get** `/organization/certificates` - - `api_key_id: optional string` +List uploaded certificates for this organization. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Query Parameters - - `context_level: optional string` +- `after: optional string` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `model: optional string` +- `limit: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `project_id: optional string` +- `order: optional "asc" or "desc"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `user_id: optional string` + - `"asc"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"desc"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +### Returns - The aggregated costs details of the specific time bucket. +- `data: array of object { id, active, certificate_details, 3 more }` - - `object: "organization.costs.result"` + - `id: string` - - `"organization.costs.result"` + The identifier, which can be referenced in API endpoints - - `amount: optional object { currency, value }` + - `active: boolean` - The monetary value in its associated currency. + Whether the certificate is currently active at the organization level. - - `currency: optional string` + - `certificate_details: object { expires_at, valid_at }` - Lowercase ISO-4217 currency e.g. "usd" + - `expires_at: optional number` - - `value: optional number` + The Unix timestamp (in seconds) of when the certificate expires. - The numeric value of the cost. + - `valid_at: optional number` - - `api_key_id: optional string` + The Unix timestamp (in seconds) of when the certificate becomes valid. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `created_at: number` - - `line_item: optional string` + The Unix timestamp (in seconds) of when the certificate was uploaded. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `name: string` - - `project_id: optional string` + The name of the certificate. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `object: "organization.certificate"` - - `quantity: optional number` + The object type, which is always `organization.certificate`. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `"organization.certificate"` - - `start_time: number` +- `first_id: string` - `has_more: boolean` -- `next_page: string` +- `last_id: string` -- `object: "page"` +- `object: "list"` - - `"page"` + - `"list"` ### Example ```http -curl https://api.openai.com/v1/organization/usage/audio_speeches \ +curl https://api.openai.com/v1/organization/certificates \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -4380,1111 +4412,1337 @@ curl https://api.openai.com/v1/organization/usage/audio_speeches \ { "data": [ { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.certificate" } ], + "first_id": "cert_abc", "has_more": true, - "next_page": "next_page", - "object": "page" + "last_id": "cert_abc", + "object": "list" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl https://api.openai.com/v1/organization/certificates \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` #### Response ```json { - "object": "page", + "object": "list", "data": [ { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.audio_speeches.result", - "characters": 45, - "num_model_requests": 1, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] + "object": "organization.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 } + }, ], - "has_more": false, - "next_page": null + "first_id": "cert_abc", + "last_id": "cert_abc", + "has_more": false } ``` -## Audio transcriptions +## Get certificate -**get** `/organization/usage/audio_transcriptions` +**get** `/organization/certificates/{certificate_id}` + +Get a certificate that has been uploaded to the organization. + +You can get a certificate regardless of whether it is active or not. + +### Path Parameters + +- `certificate_id: string` + +### Query Parameters + +- `include: optional array of "content"` + + A list of additional fields to include in the response. Currently the only supported value is `content` to fetch the PEM content of the certificate. + + - `"content"` + +### Returns + +- `Certificate object { id, certificate_details, created_at, 3 more }` + + Represents an individual `certificate` uploaded to the organization. + + - `id: string` + + The identifier, which can be referenced in API endpoints + + - `certificate_details: object { content, expires_at, valid_at }` + + - `content: optional string` + + The content of the certificate in PEM format. + + - `expires_at: optional number` + + The Unix timestamp (in seconds) of when the certificate expires. + + - `valid_at: optional number` + + The Unix timestamp (in seconds) of when the certificate becomes valid. + + - `created_at: number` -Get audio transcriptions usage details for the organization. + The Unix timestamp (in seconds) of when the certificate was uploaded. -### Query Parameters + - `name: string` -- `start_time: number` + The name of the certificate. - Start time (Unix seconds) of the query time range, inclusive. + - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` -- `api_key_ids: optional array of string` + The object type. - Return only usage for these API keys. + - If creating, updating, or getting a specific certificate, the object type is `certificate`. + - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. + - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. -- `bucket_width: optional "1m" or "1h" or "1d"` + - `"certificate"` - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + - `"organization.certificate"` - - `"1m"` + - `"organization.project.certificate"` - - `"1h"` + - `active: optional boolean` - - `"1d"` + Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. -- `end_time: optional number` +### Example - End time (Unix seconds) of the query time range, exclusive. +```http +curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` +#### Response - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. +```json +{ + "id": "id", + "certificate_details": { + "content": "content", + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "certificate", + "active": true +} +``` - - `"project_id"` +### Example - - `"user_id"` +```http +curl "https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"api_key_id"` +#### Response - - `"model"` +```json +{ + "object": "certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 1234567, + "expires_at": 12345678, + "content": "-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----" + } +} +``` -- `limit: optional number` +## Modify certificate - Specifies the number of buckets to return. +**post** `/organization/certificates/{certificate_id}` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 +Modify a certificate. Note that only the name can be modified. -- `models: optional array of string` +### Path Parameters - Return only usage for these models. +- `certificate_id: string` -- `page: optional string` +### Body Parameters - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. +- `name: optional string` -- `project_ids: optional array of string` + The updated name for the certificate - Return only usage for these projects. +### Returns -- `user_ids: optional array of string` +- `Certificate object { id, certificate_details, created_at, 3 more }` - Return only usage for these users. + Represents an individual `certificate` uploaded to the organization. -### Returns + - `id: string` -- `data: array of object { end_time, object, results, start_time }` + The identifier, which can be referenced in API endpoints - - `end_time: number` + - `certificate_details: object { content, expires_at, valid_at }` - - `object: "bucket"` + - `content: optional string` - - `"bucket"` + The content of the certificate in PEM format. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `expires_at: optional number` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + The Unix timestamp (in seconds) of when the certificate expires. - The aggregated completions usage details of the specific time bucket. + - `valid_at: optional number` - - `input_tokens: number` + The Unix timestamp (in seconds) of when the certificate becomes valid. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `created_at: number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of when the certificate was uploaded. - The count of requests made to the model. + - `name: string` - - `object: "organization.usage.completions.result"` + The name of the certificate. - - `"organization.usage.completions.result"` + - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` - - `output_tokens: number` + The object type. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - If creating, updating, or getting a specific certificate, the object type is `certificate`. + - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. + - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. - - `api_key_id: optional string` + - `"certificate"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"organization.certificate"` - - `batch: optional boolean` + - `"organization.project.certificate"` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `active: optional boolean` - - `input_audio_tokens: optional number` + Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. - The aggregated number of uncached audio input tokens used. +### Example - - `input_cache_write_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - The aggregated number of input tokens written to the cache. +#### Response - - `input_cached_audio_tokens: optional number` +```json +{ + "id": "id", + "certificate_details": { + "content": "content", + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "certificate", + "active": true +} +``` - The aggregated number of cached audio input tokens used. +### Example - - `input_cached_image_tokens: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/certificates/cert_abc \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "name": "Renamed Certificate" +}' +``` - The aggregated number of cached image input tokens used. +#### Response - - `input_cached_text_tokens: optional number` +```json +{ + "object": "certificate", + "id": "cert_abc", + "name": "Renamed Certificate", + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } +} +``` - The aggregated number of cached text input tokens used. +## Domain Types - - `input_cached_tokens: optional number` +### Certificate - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `Certificate object { id, certificate_details, created_at, 3 more }` - - `input_image_tokens: optional number` + Represents an individual `certificate` uploaded to the organization. - The aggregated number of uncached image input tokens used. + - `id: string` - - `input_text_tokens: optional number` + The identifier, which can be referenced in API endpoints - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `certificate_details: object { content, expires_at, valid_at }` - - `input_uncached_tokens: optional number` + - `content: optional string` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + The content of the certificate in PEM format. - - `model: optional string` + - `expires_at: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate expires. - - `output_audio_tokens: optional number` + - `valid_at: optional number` - The aggregated number of audio output tokens used. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `output_image_tokens: optional number` + - `created_at: number` - The aggregated number of image output tokens used. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `output_text_tokens: optional number` + - `name: string` - The aggregated number of text output tokens used. + The name of the certificate. - - `project_id: optional string` + - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The object type. - - `service_tier: optional string` + - If creating, updating, or getting a specific certificate, the object type is `certificate`. + - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. + - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `"certificate"` - - `user_id: optional string` + - `"organization.certificate"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"organization.project.certificate"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + - `active: optional boolean` - The aggregated embeddings usage details of the specific time bucket. + Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. - - `input_tokens: number` +### Certificate Activate Response - The aggregated number of input tokens used. +- `CertificateActivateResponse object { id, active, certificate_details, 3 more }` - - `num_model_requests: number` + Represents an individual certificate configured at the organization level. - The count of requests made to the model. + - `id: string` - - `object: "organization.usage.embeddings.result"` + The identifier, which can be referenced in API endpoints - - `"organization.usage.embeddings.result"` + - `active: boolean` - - `api_key_id: optional string` + Whether the certificate is currently active at the organization level. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `certificate_details: object { expires_at, valid_at }` - - `model: optional string` + - `expires_at: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate expires. - - `project_id: optional string` + - `valid_at: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `user_id: optional string` + - `created_at: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `name: string` - The aggregated moderations usage details of the specific time bucket. + The name of the certificate. - - `input_tokens: number` + - `object: "organization.certificate"` - The aggregated number of input tokens used. + The object type, which is always `organization.certificate`. - - `num_model_requests: number` + - `"organization.certificate"` - The count of requests made to the model. +### Certificate Deactivate Response - - `object: "organization.usage.moderations.result"` +- `CertificateDeactivateResponse object { id, active, certificate_details, 3 more }` - - `"organization.usage.moderations.result"` + Represents an individual certificate configured at the organization level. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `model: optional string` + - `active: boolean` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the certificate is currently active at the organization level. - - `project_id: optional string` + - `certificate_details: object { expires_at, valid_at }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `expires_at: optional number` - - `user_id: optional string` + The Unix timestamp (in seconds) of when the certificate expires. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `valid_at: optional number` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + The Unix timestamp (in seconds) of when the certificate becomes valid. - The aggregated images usage details of the specific time bucket. + - `created_at: number` - - `images: number` + The Unix timestamp (in seconds) of when the certificate was uploaded. - The number of images processed. + - `name: string` - - `num_model_requests: number` + The name of the certificate. - The count of requests made to the model. + - `object: "organization.certificate"` - - `object: "organization.usage.images.result"` + The object type, which is always `organization.certificate`. - - `"organization.usage.images.result"` + - `"organization.certificate"` - - `api_key_id: optional string` +### Certificate Delete Response - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `CertificateDeleteResponse object { id, object }` - - `model: optional string` + - `id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + The ID of the certificate that was deleted. - - `project_id: optional string` + - `object: "certificate.deleted"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The object type, must be `certificate.deleted`. - - `size: optional string` + - `"certificate.deleted"` - When `group_by=size`, this field provides the image size of the grouped usage result. +### Certificate List Response - - `source: optional string` +- `CertificateListResponse object { id, active, certificate_details, 3 more }` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + Represents an individual certificate configured at the organization level. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `active: boolean` - The aggregated audio speeches usage details of the specific time bucket. + Whether the certificate is currently active at the organization level. - - `characters: number` + - `certificate_details: object { expires_at, valid_at }` - The number of characters processed. + - `expires_at: optional number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of when the certificate expires. - The count of requests made to the model. + - `valid_at: optional number` - - `object: "organization.usage.audio_speeches.result"` + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `"organization.usage.audio_speeches.result"` + - `created_at: number` - - `api_key_id: optional string` + The Unix timestamp (in seconds) of when the certificate was uploaded. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `name: string` - - `model: optional string` + The name of the certificate. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "organization.certificate"` - - `project_id: optional string` + The object type, which is always `organization.certificate`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.certificate"` - - `user_id: optional string` +# Data Retention - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Retrieve organization data retention - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +**get** `/organization/data_retention` - The aggregated audio transcriptions usage details of the specific time bucket. +Retrieves organization data retention controls. - - `num_model_requests: number` +### Returns - The count of requests made to the model. +- `OrganizationDataRetention object { object, type }` - - `object: "organization.usage.audio_transcriptions.result"` + Represents the organization's data retention control setting. - - `"organization.usage.audio_transcriptions.result"` + - `object: "organization.data_retention"` - - `seconds: number` + The object type, which is always `organization.data_retention`. - The number of seconds processed. + - `"organization.data_retention"` - - `api_key_id: optional string` + - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The configured organization data retention type. - - `model: optional string` + - `"zero_data_retention"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"modified_abuse_monitoring"` - - `project_id: optional string` + - `"enhanced_zero_data_retention"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"enhanced_modified_abuse_monitoring"` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +#### Response - The aggregated vector stores usage details of the specific time bucket. +```json +{ + "object": "organization.data_retention", + "type": "zero_data_retention" +} +``` - - `object: "organization.usage.vector_stores.result"` +### Example - - `"organization.usage.vector_stores.result"` +```http +curl https://api.openai.com/v1/organization/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `usage_bytes: number` +#### Response - The vector stores usage in bytes. +```json +{ + "object": "organization.data_retention", + "type": "modified_abuse_monitoring" +} +``` - - `project_id: optional string` +## Update organization data retention - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**post** `/organization/data_retention` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +Updates organization data retention controls. - The aggregated code interpreter sessions usage details of the specific time bucket. +### Body Parameters - - `num_sessions: number` +- `retention_type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` - The number of code interpreter sessions. + The desired organization data retention type. - - `object: "organization.usage.code_interpreter_sessions.result"` + - `"zero_data_retention"` - - `"organization.usage.code_interpreter_sessions.result"` + - `"modified_abuse_monitoring"` - - `project_id: optional string` + - `"enhanced_zero_data_retention"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"enhanced_modified_abuse_monitoring"` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +### Returns - The aggregated file search calls usage details of the specific time bucket. +- `OrganizationDataRetention object { object, type }` - - `num_requests: number` + Represents the organization's data retention control setting. - The count of file search calls. + - `object: "organization.data_retention"` - - `object: "organization.usage.file_searches.result"` + The object type, which is always `organization.data_retention`. - - `"organization.usage.file_searches.result"` + - `"organization.data_retention"` - - `api_key_id: optional string` + - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The configured organization data retention type. - - `project_id: optional string` + - `"zero_data_retention"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"modified_abuse_monitoring"` - - `user_id: optional string` + - `"enhanced_zero_data_retention"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"enhanced_modified_abuse_monitoring"` - - `vector_store_id: optional string` +### Example - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/data_retention \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "retention_type": "zero_data_retention" + }' +``` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +#### Response - The aggregated web search calls usage details of the specific time bucket. +```json +{ + "object": "organization.data_retention", + "type": "zero_data_retention" +} +``` - - `num_model_requests: number` +### Example - The count of model requests. +```http +curl -X POST https://api.openai.com/v1/organization/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "retention_type": "modified_abuse_monitoring" + }' +``` - - `num_requests: number` +#### Response - The count of web search calls. +```json +{ + "object": "organization.data_retention", + "type": "modified_abuse_monitoring" +} +``` - - `object: "organization.usage.web_searches.result"` +## Domain Types - - `"organization.usage.web_searches.result"` +### Organization Data Retention - - `api_key_id: optional string` +- `OrganizationDataRetention object { object, type }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Represents the organization's data retention control setting. - - `context_level: optional string` + - `object: "organization.data_retention"` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + The object type, which is always `organization.data_retention`. - - `model: optional string` + - `"organization.data_retention"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` - - `project_id: optional string` + The configured organization data retention type. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"zero_data_retention"` - - `user_id: optional string` + - `"modified_abuse_monitoring"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"enhanced_zero_data_retention"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `"enhanced_modified_abuse_monitoring"` - The aggregated costs details of the specific time bucket. +# Groups - - `object: "organization.costs.result"` +## Create group - - `"organization.costs.result"` +**post** `/organization/groups` - - `amount: optional object { currency, value }` +Creates a new group in the organization. - The monetary value in its associated currency. +### Body Parameters - - `currency: optional string` +- `name: string` - Lowercase ISO-4217 currency e.g. "usd" + Human readable name for the group. - - `value: optional number` +### Returns - The numeric value of the cost. +- `Group object { id, created_at, group_type, 2 more }` - - `api_key_id: optional string` + Details about an organization group. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `id: string` - - `line_item: optional string` + Identifier for the group. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `created_at: number` - - `project_id: optional string` + Unix timestamp (in seconds) when the group was created. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `group_type: "group" or "tenant_group"` - - `quantity: optional number` + The type of the group. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `"group"` - - `start_time: number` + - `"tenant_group"` -- `has_more: boolean` + - `is_scim_managed: boolean` -- `next_page: string` + Whether the group is managed through SCIM and controlled by your identity provider. -- `object: "page"` + - `name: string` - - `"page"` + Display name of the group. ### Example ```http -curl https://api.openai.com/v1/organization/usage/audio_transcriptions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +curl https://api.openai.com/v1/organization/groups \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "name": "x" + }' ``` #### Response ```json { - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" + "id": "id", + "created_at": 0, + "group_type": "group", + "is_scim_managed": true, + "name": "name" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl -X POST https://api.openai.com/v1/organization/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Support Team" + }' ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.audio_transcriptions.result", - "seconds": 20, - "num_model_requests": 1, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] - } - ], - "has_more": false, - "next_page": null + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false } ``` -## Code interpreter sessions - -**get** `/organization/usage/code_interpreter_sessions` - -Get code interpreter sessions usage details for the organization. - -### Query Parameters - -- `start_time: number` - - Start time (Unix seconds) of the query time range, inclusive. - -- `bucket_width: optional "1m" or "1h" or "1d"` - - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - - `"1m"` - - - `"1h"` - - - `"1d"` - -- `end_time: optional number` - - End time (Unix seconds) of the query time range, exclusive. - -- `group_by: optional array of "project_id"` - - Group the usage data by the specified fields. Support fields include `project_id`. - - - `"project_id"` +## Delete group -- `limit: optional number` +**delete** `/organization/groups/{group_id}` - Specifies the number of buckets to return. +Deletes a group from the organization. - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 +### Path Parameters -- `page: optional string` +- `group_id: string` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. +### Returns -- `project_ids: optional array of string` +- `id: string` - Return only usage for these projects. + Identifier of the deleted group. -### Returns +- `deleted: boolean` -- `data: array of object { end_time, object, results, start_time }` + Whether the group was deleted. - - `end_time: number` +- `object: "group.deleted"` - - `object: "bucket"` + Always `group.deleted`. - - `"bucket"` + - `"group.deleted"` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +### Example - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated completions usage details of the specific time bucket. +#### Response - - `input_tokens: number` +```json +{ + "id": "id", + "deleted": true, + "object": "group.deleted" +} +``` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Example - - `num_model_requests: number` +```http +curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The count of requests made to the model. +#### Response - - `object: "organization.usage.completions.result"` +```json +{ + "object": "group.deleted", + "id": "group_01J1F8ABCDXYZ", + "deleted": true +} +``` - - `"organization.usage.completions.result"` +## List groups - - `output_tokens: number` +**get** `/organization/groups` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +Lists all groups in the organization. - - `api_key_id: optional string` +### Query Parameters - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `after: optional string` - - `batch: optional boolean` + A cursor for use in pagination. `after` is a group ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with group_abc, your subsequent call can include `after=group_abc` in order to fetch the next page of the list. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +- `limit: optional number` - - `input_audio_tokens: optional number` + A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the default is 100. - The aggregated number of uncached audio input tokens used. +- `order: optional "asc" or "desc"` - - `input_cache_write_tokens: optional number` + Specifies the sort order of the returned groups. - The aggregated number of input tokens written to the cache. + - `"asc"` - - `input_cached_audio_tokens: optional number` + - `"desc"` - The aggregated number of cached audio input tokens used. +### Returns - - `input_cached_image_tokens: optional number` +- `data: array of Group` - The aggregated number of cached image input tokens used. + Groups returned in the current page. - - `input_cached_text_tokens: optional number` + - `id: string` - The aggregated number of cached text input tokens used. + Identifier for the group. - - `input_cached_tokens: optional number` + - `created_at: number` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Unix timestamp (in seconds) when the group was created. - - `input_image_tokens: optional number` + - `group_type: "group" or "tenant_group"` - The aggregated number of uncached image input tokens used. + The type of the group. - - `input_text_tokens: optional number` + - `"group"` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `"tenant_group"` - - `input_uncached_tokens: optional number` + - `is_scim_managed: boolean` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + Whether the group is managed through SCIM and controlled by your identity provider. - - `model: optional string` + - `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Display name of the group. - - `output_audio_tokens: optional number` +- `has_more: boolean` - The aggregated number of audio output tokens used. + Whether additional groups are available when paginating. - - `output_image_tokens: optional number` +- `next: string` - The aggregated number of image output tokens used. + Cursor to fetch the next page of results, or `null` if there are no more results. - - `output_text_tokens: optional number` +- `object: "list"` - The aggregated number of text output tokens used. + Always `list`. - - `project_id: optional string` + - `"list"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Example - - `service_tier: optional string` +```http +curl https://api.openai.com/v1/organization/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "group_type": "group", + "is_scim_managed": true, + "name": "name" + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +```http +curl https://api.openai.com/v1/organization/groups?limit=20&order=asc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated embeddings usage details of the specific time bucket. +#### Response - - `input_tokens: number` +```json +{ + "object": "list", + "data": [ + { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false + } + ], + "has_more": false, + "next": null +} +``` - The aggregated number of input tokens used. +## Retrieve group - - `num_model_requests: number` +**get** `/organization/groups/{group_id}` - The count of requests made to the model. +Retrieves a group. - - `object: "organization.usage.embeddings.result"` +### Path Parameters - - `"organization.usage.embeddings.result"` +- `group_id: string` - - `api_key_id: optional string` +### Returns - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `Group object { id, created_at, group_type, 2 more }` - - `model: optional string` + Details about an organization group. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Identifier for the group. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `created_at: number` - - `user_id: optional string` + Unix timestamp (in seconds) when the group was created. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `group_type: "group" or "tenant_group"` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + The type of the group. - The aggregated moderations usage details of the specific time bucket. + - `"group"` - - `input_tokens: number` + - `"tenant_group"` - The aggregated number of input tokens used. + - `is_scim_managed: boolean` - - `num_model_requests: number` + Whether the group is managed through SCIM and controlled by your identity provider. - The count of requests made to the model. + - `name: string` - - `object: "organization.usage.moderations.result"` + Display name of the group. - - `"organization.usage.moderations.result"` +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "id": "id", + "created_at": 0, + "group_type": "group", + "is_scim_managed": true, + "name": "name" +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "is_scim_managed": false, + "group_type": "group" +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Update group - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +**post** `/organization/groups/{group_id}` - The aggregated images usage details of the specific time bucket. +Updates a group's information. - - `images: number` +### Path Parameters - The number of images processed. +- `group_id: string` - - `num_model_requests: number` +### Body Parameters - The count of requests made to the model. +- `name: string` - - `object: "organization.usage.images.result"` + New display name for the group. - - `"organization.usage.images.result"` +### Returns - - `api_key_id: optional string` +- `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Identifier for the group. - - `model: optional string` +- `created_at: number` - When `group_by=model`, this field provides the model name of the grouped usage result. + Unix timestamp (in seconds) when the group was created. - - `project_id: optional string` +- `is_scim_managed: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether the group is managed through SCIM and controlled by your identity provider. - - `size: optional string` +- `name: string` - When `group_by=size`, this field provides the image size of the grouped usage result. + Updated display name for the group. - - `source: optional string` +### Example - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "name": "x" + }' +``` - - `user_id: optional string` +#### Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```json +{ + "id": "id", + "created_at": 0, + "is_scim_managed": true, + "name": "name" +} +``` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +### Example - The aggregated audio speeches usage details of the specific time bucket. +```http +curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Escalations" + }' +``` - - `characters: number` +#### Response - The number of characters processed. +```json +{ + "id": "group_01J1F8ABCDXYZ", + "name": "Escalations", + "created_at": 1711471533, + "is_scim_managed": false +} +``` - - `num_model_requests: number` +## Domain Types - The count of requests made to the model. +### Group - - `object: "organization.usage.audio_speeches.result"` +- `Group object { id, created_at, group_type, 2 more }` - - `"organization.usage.audio_speeches.result"` + Details about an organization group. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Identifier for the group. - - `model: optional string` + - `created_at: number` - When `group_by=model`, this field provides the model name of the grouped usage result. + Unix timestamp (in seconds) when the group was created. - - `project_id: optional string` + - `group_type: "group" or "tenant_group"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The type of the group. - - `user_id: optional string` + - `"group"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"tenant_group"` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `is_scim_managed: boolean` - The aggregated audio transcriptions usage details of the specific time bucket. + Whether the group is managed through SCIM and controlled by your identity provider. - - `num_model_requests: number` + - `name: string` - The count of requests made to the model. + Display name of the group. - - `object: "organization.usage.audio_transcriptions.result"` +### Group Delete Response - - `"organization.usage.audio_transcriptions.result"` +- `GroupDeleteResponse object { id, deleted, object }` - - `seconds: number` + Confirmation payload returned after deleting a group. - The number of seconds processed. + - `id: string` - - `api_key_id: optional string` + Identifier of the deleted group. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `deleted: boolean` - - `model: optional string` + Whether the group was deleted. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "group.deleted"` - - `project_id: optional string` + Always `group.deleted`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"group.deleted"` - - `user_id: optional string` +### Group Update Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `GroupUpdateResponse object { id, created_at, is_scim_managed, name }` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + Response returned after updating a group. - The aggregated vector stores usage details of the specific time bucket. + - `id: string` - - `object: "organization.usage.vector_stores.result"` + Identifier for the group. - - `"organization.usage.vector_stores.result"` + - `created_at: number` - - `usage_bytes: number` + Unix timestamp (in seconds) when the group was created. - The vector stores usage in bytes. + - `is_scim_managed: boolean` - - `project_id: optional string` + Whether the group is managed through SCIM and controlled by your identity provider. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `name: string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + Updated display name for the group. - The aggregated code interpreter sessions usage details of the specific time bucket. +# Roles - - `num_sessions: number` +## Assign organization role to group - The number of code interpreter sessions. +**post** `/organization/groups/{group_id}/roles` - - `object: "organization.usage.code_interpreter_sessions.result"` +Assigns an organization role to a group within the organization. - - `"organization.usage.code_interpreter_sessions.result"` +### Path Parameters - - `project_id: optional string` +- `group_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Body Parameters - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +- `role_id: string` - The aggregated file search calls usage details of the specific time bucket. + Identifier of the role to assign. - - `num_requests: number` +### Returns - The count of file search calls. +- `group: object { id, created_at, name, 2 more }` - - `object: "organization.usage.file_searches.result"` + Summary information about a group returned in role assignment responses. - - `"organization.usage.file_searches.result"` + - `id: string` - - `api_key_id: optional string` + Identifier for the group. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `created_at: number` - - `project_id: optional string` + Unix timestamp (in seconds) when the group was created. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `name: string` - - `user_id: optional string` + Display name of the group. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `object: "group"` - - `vector_store_id: optional string` + Always `group`. - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `"group"` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `scim_managed: boolean` - The aggregated web search calls usage details of the specific time bucket. + Whether the group is managed through SCIM. - - `num_model_requests: number` +- `object: "group.role"` - The count of model requests. + Always `group.role`. - - `num_requests: number` + - `"group.role"` - The count of web search calls. +- `role: Role` - - `object: "organization.usage.web_searches.result"` + Details about a role that can be assigned through the public Roles API. - - `"organization.usage.web_searches.result"` + - `id: string` - - `api_key_id: optional string` + Identifier for the role. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `description: string` - - `context_level: optional string` + Optional description of the role. - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + - `name: string` - - `model: optional string` + Unique name for the role. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "role"` - - `project_id: optional string` + Always `role`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"role"` - - `user_id: optional string` + - `permissions: array of string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Permissions granted by the role. - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `predefined_role: boolean` - The aggregated costs details of the specific time bucket. + Whether the role is predefined and managed by OpenAI. - - `object: "organization.costs.result"` + - `resource_type: string` - - `"organization.costs.result"` + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `amount: optional object { currency, value }` +### Example - The monetary value in its associated currency. +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "role_id": "role_id" + }' +``` - - `currency: optional string` +#### Response - Lowercase ISO-4217 currency e.g. "usd" +```json +{ + "group": { + "id": "id", + "created_at": 0, + "name": "name", + "object": "group", + "scim_managed": true + }, + "object": "group.role", + "role": { + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" + } +} +``` - - `value: optional number` +### Example - The numeric value of the cost. +```http +curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8ROLE01" + }' +``` - - `api_key_id: optional string` +#### Response - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +```json +{ + "object": "group.role", + "group": { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } +} +``` - - `line_item: optional string` +## Unassign organization role from group - When `group_by=line_item`, this field provides the line item of the grouped costs result. +**delete** `/organization/groups/{group_id}/roles/{role_id}` - - `project_id: optional string` +Unassigns an organization role from a group within the organization. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +### Path Parameters - - `quantity: optional number` +- `group_id: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +- `role_id: string` - - `start_time: number` +### Returns -- `has_more: boolean` +- `deleted: boolean` -- `next_page: string` + Whether the assignment was removed. -- `object: "page"` +- `object: string` - - `"page"` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. ### Example ```http -curl https://api.openai.com/v1/organization/usage/code_interpreter_sessions \ +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles/$ROLE_ID \ + -X DELETE \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -5492,1150 +5750,1309 @@ curl https://api.openai.com/v1/organization/usage/code_interpreter_sessions \ ```json { - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" + "deleted": true, + "object": "object" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.code_interpreter_sessions.result", - "num_sessions": 1, - "project_id": null - } - ] - } - ], - "has_more": false, - "next_page": null + "object": "group.role.deleted", + "deleted": true } ``` -## Completions - -**get** `/organization/usage/completions` - -Get completions usage details for the organization. - -### Query Parameters - -- `start_time: number` - - Start time (Unix seconds) of the query time range, inclusive. +## List group organization role assignments -- `api_key_ids: optional array of string` +**get** `/organization/groups/{group_id}/roles` - Return only usage for these API keys. +Lists the organization roles assigned to a group within the organization. -- `batch: optional boolean` +### Path Parameters - If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both. +- `group_id: string` -- `bucket_width: optional "1m" or "1h" or "1d"` +### Query Parameters - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. +- `after: optional string` - - `"1m"` + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles. - - `"1h"` +- `limit: optional number` - - `"1d"` + A limit on the number of organization role assignments to return. -- `end_time: optional number` +- `order: optional "asc" or "desc"` - End time (Unix seconds) of the query time range, exclusive. + Sort order for the returned organization roles. -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 3 more` + - `"asc"` - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier` or any combination of them. + - `"desc"` - - `"project_id"` +### Returns - - `"user_id"` +- `data: array of object { id, assignment_sources, created_at, 9 more }` - - `"api_key_id"` + Role assignments returned in the current page. - - `"model"` + - `id: string` - - `"batch"` + Identifier for the role. - - `"service_tier"` + - `assignment_sources: array of object { principal_id, principal_type }` -- `limit: optional number` + Principals from which the role assignment is inherited, when available. - Specifies the number of buckets to return. + - `principal_id: string` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + - `principal_type: string` -- `models: optional array of string` + - `created_at: number` - Return only usage for these models. + When the role was created. -- `page: optional string` + - `created_by: string` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + Identifier of the actor who created the role. -- `project_ids: optional array of string` + - `created_by_user_obj: map[unknown]` - Return only usage for these projects. + User details for the actor that created the role, when available. -- `user_ids: optional array of string` + - `description: string` - Return only usage for these users. + Description of the role. -### Returns + - `metadata: map[unknown]` -- `data: array of object { end_time, object, results, start_time }` + Arbitrary metadata stored on the role. - - `end_time: number` + - `name: string` - - `object: "bucket"` + Name of the role. - - `"bucket"` + - `permissions: array of string` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + Permissions associated with the role. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `predefined_role: boolean` - The aggregated completions usage details of the specific time bucket. + Whether the role is predefined by OpenAI. - - `input_tokens: number` + - `resource_type: string` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Resource type the role applies to. - - `num_model_requests: number` + - `updated_at: number` - The count of requests made to the model. + When the role was last updated. - - `object: "organization.usage.completions.result"` +- `has_more: boolean` - - `"organization.usage.completions.result"` + Whether additional assignments are available when paginating. - - `output_tokens: number` +- `next: string` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Cursor to fetch the next page of results, or `null` when there are no more assignments. - - `api_key_id: optional string` +- `object: "list"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Always `list`. - - `batch: optional boolean` + - `"list"` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +### Example - - `input_audio_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated number of uncached audio input tokens used. +#### Response - - `input_cache_write_tokens: optional number` +```json +{ + "data": [ + { + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - The aggregated number of input tokens written to the cache. +### Example - - `input_cached_audio_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated number of cached audio input tokens used. +#### Response - - `input_cached_image_tokens: optional number` +```json +{ + "object": "list", + "data": [ + { + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null +} +``` - The aggregated number of cached image input tokens used. +## Retrieve group organization role - - `input_cached_text_tokens: optional number` +**get** `/organization/groups/{group_id}/roles/{role_id}` - The aggregated number of cached text input tokens used. +Retrieves an organization role assigned to a group. - - `input_cached_tokens: optional number` +### Path Parameters - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `group_id: string` - - `input_image_tokens: optional number` +- `role_id: string` - The aggregated number of uncached image input tokens used. +### Returns - - `input_text_tokens: optional number` +- `id: string` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + Identifier for the role. - - `input_uncached_tokens: optional number` +- `assignment_sources: array of object { principal_id, principal_type }` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + Principals from which the role assignment is inherited, when available. - - `model: optional string` + - `principal_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `principal_type: string` - - `output_audio_tokens: optional number` +- `created_at: number` - The aggregated number of audio output tokens used. + When the role was created. - - `output_image_tokens: optional number` +- `created_by: string` - The aggregated number of image output tokens used. + Identifier of the actor who created the role. - - `output_text_tokens: optional number` +- `created_by_user_obj: map[unknown]` - The aggregated number of text output tokens used. + User details for the actor that created the role, when available. - - `project_id: optional string` +- `description: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Description of the role. - - `service_tier: optional string` +- `metadata: map[unknown]` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + Arbitrary metadata stored on the role. - - `user_id: optional string` +- `name: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Name of the role. - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +- `permissions: array of string` - The aggregated embeddings usage details of the specific time bucket. + Permissions associated with the role. - - `input_tokens: number` +- `predefined_role: boolean` - The aggregated number of input tokens used. + Whether the role is predefined by OpenAI. - - `num_model_requests: number` +- `resource_type: string` - The count of requests made to the model. + Resource type the role applies to. - - `object: "organization.usage.embeddings.result"` +- `updated_at: number` - - `"organization.usage.embeddings.result"` + When the role was last updated. - - `api_key_id: optional string` +### Example - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles/$ROLE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `model: optional string` +#### Response - When `group_by=model`, this field provides the model name of the grouped usage result. +```json +{ + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 +} +``` - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `user_id: optional string` +#### Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```json +{ + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": null, + "metadata": {}, + "assignment_sources": null +} +``` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +## Domain Types - The aggregated moderations usage details of the specific time bucket. +### Role Create Response - - `input_tokens: number` +- `RoleCreateResponse object { group, object, role }` - The aggregated number of input tokens used. + Role assignment linking a group to a role. - - `num_model_requests: number` + - `group: object { id, created_at, name, 2 more }` - The count of requests made to the model. + Summary information about a group returned in role assignment responses. - - `object: "organization.usage.moderations.result"` + - `id: string` - - `"organization.usage.moderations.result"` + Identifier for the group. - - `api_key_id: optional string` + - `created_at: number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Unix timestamp (in seconds) when the group was created. - - `model: optional string` + - `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Display name of the group. - - `project_id: optional string` + - `object: "group"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Always `group`. - - `user_id: optional string` + - `"group"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `scim_managed: boolean` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + Whether the group is managed through SCIM. - The aggregated images usage details of the specific time bucket. + - `object: "group.role"` - - `images: number` + Always `group.role`. - The number of images processed. + - `"group.role"` - - `num_model_requests: number` + - `role: Role` - The count of requests made to the model. + Details about a role that can be assigned through the public Roles API. - - `object: "organization.usage.images.result"` + - `id: string` - - `"organization.usage.images.result"` + Identifier for the role. - - `api_key_id: optional string` + - `description: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Optional description of the role. - - `model: optional string` + - `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Unique name for the role. - - `project_id: optional string` + - `object: "role"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Always `role`. - - `size: optional string` + - `"role"` - When `group_by=size`, this field provides the image size of the grouped usage result. + - `permissions: array of string` - - `source: optional string` + Permissions granted by the role. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `predefined_role: boolean` - - `user_id: optional string` + Whether the role is predefined and managed by OpenAI. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `resource_type: string` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + Resource type the role is bound to (for example `api.organization` or `api.project`). - The aggregated audio speeches usage details of the specific time bucket. +### Role Delete Response - - `characters: number` +- `RoleDeleteResponse object { deleted, object }` - The number of characters processed. + Confirmation payload returned after unassigning a role. - - `num_model_requests: number` + - `deleted: boolean` - The count of requests made to the model. + Whether the assignment was removed. - - `object: "organization.usage.audio_speeches.result"` + - `object: string` - - `"organization.usage.audio_speeches.result"` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. - - `api_key_id: optional string` +### Role List Response - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` - - `model: optional string` + Detailed information about a role assignment entry returned when listing assignments. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Identifier for the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `assignment_sources: array of object { principal_id, principal_type }` - - `user_id: optional string` + Principals from which the role assignment is inherited, when available. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `principal_id: string` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `principal_type: string` - The aggregated audio transcriptions usage details of the specific time bucket. + - `created_at: number` - - `num_model_requests: number` + When the role was created. - The count of requests made to the model. + - `created_by: string` - - `object: "organization.usage.audio_transcriptions.result"` + Identifier of the actor who created the role. - - `"organization.usage.audio_transcriptions.result"` + - `created_by_user_obj: map[unknown]` - - `seconds: number` + User details for the actor that created the role, when available. - The number of seconds processed. + - `description: string` - - `api_key_id: optional string` + Description of the role. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `metadata: map[unknown]` - - `model: optional string` + Arbitrary metadata stored on the role. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `name: string` - - `project_id: optional string` + Name of the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `permissions: array of string` - - `user_id: optional string` + Permissions associated with the role. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `predefined_role: boolean` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + Whether the role is predefined by OpenAI. - The aggregated vector stores usage details of the specific time bucket. + - `resource_type: string` - - `object: "organization.usage.vector_stores.result"` + Resource type the role applies to. - - `"organization.usage.vector_stores.result"` + - `updated_at: number` - - `usage_bytes: number` + When the role was last updated. - The vector stores usage in bytes. +### Role Retrieve Response - - `project_id: optional string` +- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Detailed information about a role assignment entry returned when listing assignments. - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `id: string` - The aggregated code interpreter sessions usage details of the specific time bucket. + Identifier for the role. - - `num_sessions: number` + - `assignment_sources: array of object { principal_id, principal_type }` - The number of code interpreter sessions. + Principals from which the role assignment is inherited, when available. - - `object: "organization.usage.code_interpreter_sessions.result"` + - `principal_id: string` - - `"organization.usage.code_interpreter_sessions.result"` + - `principal_type: string` - - `project_id: optional string` + - `created_at: number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + When the role was created. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `created_by: string` - The aggregated file search calls usage details of the specific time bucket. + Identifier of the actor who created the role. - - `num_requests: number` + - `created_by_user_obj: map[unknown]` - The count of file search calls. + User details for the actor that created the role, when available. - - `object: "organization.usage.file_searches.result"` + - `description: string` - - `"organization.usage.file_searches.result"` + Description of the role. - - `api_key_id: optional string` + - `metadata: map[unknown]` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Arbitrary metadata stored on the role. - - `project_id: optional string` + - `name: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Name of the role. - - `user_id: optional string` + - `permissions: array of string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Permissions associated with the role. - - `vector_store_id: optional string` + - `predefined_role: boolean` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + Whether the role is predefined by OpenAI. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `resource_type: string` - The aggregated web search calls usage details of the specific time bucket. + Resource type the role applies to. - - `num_model_requests: number` + - `updated_at: number` - The count of model requests. + When the role was last updated. - - `num_requests: number` +# Users - The count of web search calls. +## Add group user - - `object: "organization.usage.web_searches.result"` +**post** `/organization/groups/{group_id}/users` - - `"organization.usage.web_searches.result"` +Adds a user to a group. - - `api_key_id: optional string` +### Path Parameters - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `group_id: string` - - `context_level: optional string` +### Body Parameters - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +- `user_id: string` - - `model: optional string` + Identifier of the user to add to the group. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Returns - - `project_id: optional string` +- `group_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Identifier of the group the user was added to. - - `user_id: optional string` +- `object: "group.user"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Always `group.user`. - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `"group.user"` - The aggregated costs details of the specific time bucket. +- `user_id: string` - - `object: "organization.costs.result"` + Identifier of the user that was added. - - `"organization.costs.result"` +### Example - - `amount: optional object { currency, value }` +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "user_id": "user_id" + }' +``` - The monetary value in its associated currency. +#### Response - - `currency: optional string` +```json +{ + "group_id": "group_id", + "object": "group.user", + "user_id": "user_id" +} +``` - Lowercase ISO-4217 currency e.g. "usd" +### Example - - `value: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": "user_abc123" + }' +``` - The numeric value of the cost. +#### Response - - `api_key_id: optional string` +```json +{ + "object": "group.user", + "user_id": "user_abc123", + "group_id": "group_01J1F8ABCDXYZ" +} +``` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +## Remove group user - - `line_item: optional string` +**delete** `/organization/groups/{group_id}/users/{user_id}` - When `group_by=line_item`, this field provides the line item of the grouped costs result. +Removes a user from a group. - - `project_id: optional string` +### Path Parameters - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +- `group_id: string` - - `quantity: optional number` +- `user_id: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +### Returns - - `start_time: number` +- `deleted: boolean` -- `has_more: boolean` + Whether the group membership was removed. -- `next_page: string` +- `object: "group.user.deleted"` -- `object: "page"` + Always `group.user.deleted`. - - `"page"` + - `"group.user.deleted"` ### Example ```http -curl https://api.openai.com/v1/organization/usage/completions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` - -#### Response - -```json -{ - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users/$USER_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` + +#### Response + +```json +{ + "deleted": true, + "object": "group.user.deleted" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.completions.result", - "input_tokens": 1000, - "input_cached_tokens": 400, - "input_cache_write_tokens": 100, - "input_uncached_tokens": 500, - "output_tokens": 500, - "input_text_tokens": 400, - "output_text_tokens": 400, - "input_cached_text_tokens": 300, - "input_audio_tokens": 50, - "input_cached_audio_tokens": 50, - "output_audio_tokens": 50, - "input_image_tokens": 50, - "input_cached_image_tokens": 50, - "output_image_tokens": 50, - "num_model_requests": 5, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null, - "batch": null, - "service_tier": null - } - ] - } - ], - "has_more": true, - "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" + "object": "group.user.deleted", + "deleted": true } ``` -## Embeddings +## List group users -**get** `/organization/usage/embeddings` +**get** `/organization/groups/{group_id}/users` -Get embeddings usage details for the organization. +Lists the users assigned to a group. -### Query Parameters +### Path Parameters -- `start_time: number` +- `group_id: string` - Start time (Unix seconds) of the query time range, inclusive. +### Query Parameters -- `api_key_ids: optional array of string` +- `after: optional string` - Return only usage for these API keys. + A cursor for use in pagination. Provide the ID of the last user from the previous list response to retrieve the next page. -- `bucket_width: optional "1m" or "1h" or "1d"` +- `limit: optional number` - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + A limit on the number of users to be returned. Limit can range between 0 and 1000, and the default is 100. - - `"1m"` +- `order: optional "asc" or "desc"` - - `"1h"` + Specifies the sort order of users in the list. - - `"1d"` + - `"asc"` -- `end_time: optional number` + - `"desc"` - End time (Unix seconds) of the query time range, exclusive. +### Returns -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` +- `data: array of OrganizationGroupUser` - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. + Users in the current page. - - `"project_id"` + - `id: string` - - `"user_id"` + The identifier, which can be referenced in API endpoints - - `"api_key_id"` + - `email: string` - - `"model"` + The email address of the user. -- `limit: optional number` + - `name: string` - Specifies the number of buckets to return. + The name of the user. - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 +- `has_more: boolean` -- `models: optional array of string` + Whether more users are available when paginating. - Return only usage for these models. +- `next: string` -- `page: optional string` + Cursor to fetch the next page of results, or `null` when no further users are available. - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. +- `object: "list"` -- `project_ids: optional array of string` + Always `list`. - Return only usage for these projects. + - `"list"` -- `user_ids: optional array of string` +### Example - Return only usage for these users. +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` -### Returns +#### Response -- `data: array of object { end_time, object, results, start_time }` +```json +{ + "data": [ + { + "id": "id", + "email": "email", + "name": "name" + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `end_time: number` +### Example - - `object: "bucket"` +```http +curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"bucket"` +#### Response - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +```json +{ + "object": "list", + "data": [ + { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + } + ], + "has_more": false, + "next": null +} +``` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +## Retrieve group user - The aggregated completions usage details of the specific time bucket. +**get** `/organization/groups/{group_id}/users/{user_id}` - - `input_tokens: number` +Retrieves a user in a group. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Path Parameters - - `num_model_requests: number` +- `group_id: string` - The count of requests made to the model. +- `user_id: string` - - `object: "organization.usage.completions.result"` +### Returns - - `"organization.usage.completions.result"` +- `id: string` - - `output_tokens: number` + Identifier for the user. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `email: string` - - `api_key_id: optional string` + Email address of the user, or `null` for users without an email. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `is_service_account: boolean` - - `batch: optional boolean` + Whether the user is a service account. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +- `name: string` - - `input_audio_tokens: optional number` + Display name of the user. - The aggregated number of uncached audio input tokens used. +- `picture: string` - - `input_cache_write_tokens: optional number` + URL of the user's profile picture, if available. - The aggregated number of input tokens written to the cache. +- `user_type: "user" or "tenant_user"` - - `input_cached_audio_tokens: optional number` + The type of user. - The aggregated number of cached audio input tokens used. + - `"user"` - - `input_cached_image_tokens: optional number` + - `"tenant_user"` - The aggregated number of cached image input tokens used. +### Example - - `input_cached_text_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users/$USER_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated number of cached text input tokens used. +#### Response - - `input_cached_tokens: optional number` +```json +{ + "id": "id", + "email": "email", + "is_service_account": true, + "name": "name", + "picture": "picture", + "user_type": "user" +} +``` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Example - - `input_image_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated number of uncached image input tokens used. +#### Response - - `input_text_tokens: optional number` +```json +{ + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "picture": null, + "is_service_account": false, + "user_type": "user" +} +``` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +## Domain Types - - `input_uncached_tokens: optional number` +### Organization Group User - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +- `OrganizationGroupUser object { id, email, name }` - - `model: optional string` + Represents an individual user returned when inspecting group membership. + + - `id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `output_audio_tokens: optional number` + - `email: string` - The aggregated number of audio output tokens used. + The email address of the user. - - `output_image_tokens: optional number` + - `name: string` - The aggregated number of image output tokens used. + The name of the user. - - `output_text_tokens: optional number` +### User Create Response - The aggregated number of text output tokens used. +- `UserCreateResponse object { group_id, object, user_id }` - - `project_id: optional string` + Confirmation payload returned after adding a user to a group. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `group_id: string` - - `service_tier: optional string` + Identifier of the group the user was added to. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `object: "group.user"` - - `user_id: optional string` + Always `group.user`. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"group.user"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + - `user_id: string` - The aggregated embeddings usage details of the specific time bucket. + Identifier of the user that was added. - - `input_tokens: number` +### User Delete Response - The aggregated number of input tokens used. +- `UserDeleteResponse object { deleted, object }` - - `num_model_requests: number` + Confirmation payload returned after removing a user from a group. - The count of requests made to the model. + - `deleted: boolean` - - `object: "organization.usage.embeddings.result"` + Whether the group membership was removed. - - `"organization.usage.embeddings.result"` + - `object: "group.user.deleted"` - - `api_key_id: optional string` + Always `group.user.deleted`. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"group.user.deleted"` - - `model: optional string` +### User Retrieve Response - When `group_by=model`, this field provides the model name of the grouped usage result. +- `UserRetrieveResponse object { id, email, is_service_account, 3 more }` - - `project_id: optional string` + Details about a user returned from an organization group membership lookup. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `id: string` - - `user_id: optional string` + Identifier for the user. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `email: string` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + Email address of the user, or `null` for users without an email. - The aggregated moderations usage details of the specific time bucket. + - `is_service_account: boolean` - - `input_tokens: number` + Whether the user is a service account. - The aggregated number of input tokens used. + - `name: string` - - `num_model_requests: number` + Display name of the user. - The count of requests made to the model. + - `picture: string` - - `object: "organization.usage.moderations.result"` + URL of the user's profile picture, if available. - - `"organization.usage.moderations.result"` + - `user_type: "user" or "tenant_user"` - - `api_key_id: optional string` + The type of user. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"user"` - - `model: optional string` + - `"tenant_user"` - When `group_by=model`, this field provides the model name of the grouped usage result. +# Invites - - `project_id: optional string` +## Create invite - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**post** `/organization/invites` - - `user_id: optional string` +Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Body Parameters - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +- `email: string` - The aggregated images usage details of the specific time bucket. + Send an email to this address - - `images: number` +- `role: "reader" or "owner"` - The number of images processed. + `owner` or `reader` - - `num_model_requests: number` + - `"reader"` - The count of requests made to the model. + - `"owner"` - - `object: "organization.usage.images.result"` +- `projects: optional array of object { id, role }` - - `"organization.usage.images.result"` + An array of projects to which membership is granted at the same time the org invite is accepted. If omitted, the user will be invited to the default project for compatibility with legacy behavior. If empty list is passed, the user will not be invited to any projects, including the default one. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Project's public ID - - `model: optional string` + - `role: "member" or "owner"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Project membership role - - `project_id: optional string` + - `"member"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"owner"` - - `size: optional string` +### Returns - When `group_by=size`, this field provides the image size of the grouped usage result. +- `Invite object { id, created_at, email, 6 more }` - - `source: optional string` + Represents an individual `invite` to the organization. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `id: string` - - `user_id: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `created_at: number` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + The Unix timestamp (in seconds) of when the invite was sent. - The aggregated audio speeches usage details of the specific time bucket. + - `email: string` - - `characters: number` + The email address of the individual to whom the invite was sent - The number of characters processed. + - `object: "organization.invite"` - - `num_model_requests: number` + The object type, which is always `organization.invite` - The count of requests made to the model. + - `"organization.invite"` - - `object: "organization.usage.audio_speeches.result"` + - `projects: array of object { id, role }` - - `"organization.usage.audio_speeches.result"` + The projects that were granted membership upon acceptance of the invite. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Project's public ID - - `model: optional string` + - `role: "member" or "owner"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Project membership role - - `project_id: optional string` + - `"member"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"owner"` - - `user_id: optional string` + - `role: "owner" or "reader"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + `owner` or `reader` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `"owner"` - The aggregated audio transcriptions usage details of the specific time bucket. + - `"reader"` - - `num_model_requests: number` + - `status: "accepted" or "expired" or "pending"` - The count of requests made to the model. + `accepted`,`expired`, or `pending` - - `object: "organization.usage.audio_transcriptions.result"` + - `"accepted"` - - `"organization.usage.audio_transcriptions.result"` + - `"expired"` - - `seconds: number` + - `"pending"` - The number of seconds processed. + - `accepted_at: optional number` - - `api_key_id: optional string` + The Unix timestamp (in seconds) of when the invite was accepted. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `expires_at: optional number` - - `model: optional string` + The Unix timestamp (in seconds) of when the invite expires. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/invites \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "email": "email", + "role": "reader" + }' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "id": "id", + "created_at": 0, + "email": "email", + "object": "organization.invite", + "projects": [ + { + "id": "id", + "role": "member" + } + ], + "role": "owner", + "status": "accepted", + "accepted_at": 0, + "expires_at": 0 +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +```http +curl -X POST https://api.openai.com/v1/organization/invites \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "email": "anotheruser@example.com", + "role": "reader", + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] + }' +``` - The aggregated vector stores usage details of the specific time bucket. +#### Response - - `object: "organization.usage.vector_stores.result"` +```json +{ + "object": "organization.invite", + "id": "invite-def", + "email": "anotheruser@example.com", + "role": "reader", + "status": "pending", + "created_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": null, + "projects": [ + { + "id": "project-xyz", + "role": "member" + }, + { + "id": "project-abc", + "role": "owner" + } + ] +} +``` - - `"organization.usage.vector_stores.result"` +## Delete invite - - `usage_bytes: number` +**delete** `/organization/invites/{invite_id}` - The vector stores usage in bytes. +Delete an invite. If the invite has already been accepted, it cannot be deleted. - - `project_id: optional string` +### Path Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `invite_id: string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +### Returns - The aggregated code interpreter sessions usage details of the specific time bucket. +- `id: string` - - `num_sessions: number` +- `deleted: boolean` - The number of code interpreter sessions. +- `object: "organization.invite.deleted"` - - `object: "organization.usage.code_interpreter_sessions.result"` + The object type, which is always `organization.invite.deleted` - - `"organization.usage.code_interpreter_sessions.result"` + - `"organization.invite.deleted"` - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/invites/$INVITE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +#### Response - The aggregated file search calls usage details of the specific time bucket. +```json +{ + "id": "id", + "deleted": true, + "object": "organization.invite.deleted" +} +``` - - `num_requests: number` +### Example - The count of file search calls. +```http +curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.file_searches.result"` +#### Response - - `"organization.usage.file_searches.result"` +```json +{ + "object": "organization.invite.deleted", + "id": "invite-abc", + "deleted": true +} +``` - - `api_key_id: optional string` +## List invites - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +**get** `/organization/invites` - - `project_id: optional string` +Returns a list of invites in the organization. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Query Parameters - - `user_id: optional string` +- `after: optional string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `vector_store_id: optional string` +- `limit: optional number` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +### Returns - The aggregated web search calls usage details of the specific time bucket. +- `data: array of Invite` - - `num_model_requests: number` + - `id: string` - The count of model requests. + The identifier, which can be referenced in API endpoints - - `num_requests: number` + - `created_at: number` - The count of web search calls. + The Unix timestamp (in seconds) of when the invite was sent. - - `object: "organization.usage.web_searches.result"` + - `email: string` - - `"organization.usage.web_searches.result"` + The email address of the individual to whom the invite was sent - - `api_key_id: optional string` + - `object: "organization.invite"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The object type, which is always `organization.invite` - - `context_level: optional string` + - `"organization.invite"` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + - `projects: array of object { id, role }` - - `model: optional string` + The projects that were granted membership upon acceptance of the invite. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Project's public ID - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `role: "member" or "owner"` - - `user_id: optional string` + Project membership role - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"member"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `"owner"` - The aggregated costs details of the specific time bucket. + - `role: "owner" or "reader"` - - `object: "organization.costs.result"` + `owner` or `reader` - - `"organization.costs.result"` + - `"owner"` - - `amount: optional object { currency, value }` + - `"reader"` - The monetary value in its associated currency. + - `status: "accepted" or "expired" or "pending"` - - `currency: optional string` + `accepted`,`expired`, or `pending` - Lowercase ISO-4217 currency e.g. "usd" + - `"accepted"` - - `value: optional number` + - `"expired"` - The numeric value of the cost. + - `"pending"` - - `api_key_id: optional string` + - `accepted_at: optional number` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + The Unix timestamp (in seconds) of when the invite was accepted. - - `line_item: optional string` + - `expires_at: optional number` - When `group_by=line_item`, this field provides the line item of the grouped costs result. + The Unix timestamp (in seconds) of when the invite expires. - - `project_id: optional string` +- `has_more: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + The `has_more` property is used for pagination to indicate there are additional results. - - `quantity: optional number` +- `object: "list"` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + The object type, which is always `list` - - `start_time: number` + - `"list"` -- `has_more: boolean` +- `first_id: optional string` -- `next_page: string` + The first `invite_id` in the retrieved `list` -- `object: "page"` +- `last_id: optional string` - - `"page"` + The last `invite_id` in the retrieved `list` ### Example ```http -curl https://api.openai.com/v1/organization/usage/embeddings \ +curl https://api.openai.com/v1/organization/invites \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -6645,2269 +7062,2734 @@ curl https://api.openai.com/v1/organization/usage/embeddings \ { "data": [ { - "end_time": 0, - "object": "bucket", - "results": [ + "id": "id", + "created_at": 0, + "email": "email", + "object": "organization.invite", + "projects": [ { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" + "id": "id", + "role": "member" } ], - "start_time": 0 + "role": "owner", + "status": "accepted", + "accepted_at": 0, + "expires_at": 0 } ], "has_more": true, - "next_page": "next_page", - "object": "page" + "object": "list", + "first_id": "first_id", + "last_id": "last_id" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", + "object": "list", "data": [ { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.embeddings.result", - "input_tokens": 16, - "num_model_requests": 2, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "created_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533 } ], - "has_more": false, - "next_page": null + "first_id": "invite-abc", + "last_id": "invite-abc", + "has_more": false } ``` -## Images - -**get** `/organization/usage/images` +## Retrieve invite -Get images usage details for the organization. +**get** `/organization/invites/{invite_id}` -### Query Parameters +Retrieves an invite. -- `start_time: number` +### Path Parameters - Start time (Unix seconds) of the query time range, inclusive. +- `invite_id: string` -- `api_key_ids: optional array of string` +### Returns - Return only usage for these API keys. +- `Invite object { id, created_at, email, 6 more }` -- `bucket_width: optional "1m" or "1h" or "1d"` + Represents an individual `invite` to the organization. - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + - `id: string` - - `"1m"` + The identifier, which can be referenced in API endpoints - - `"1h"` + - `created_at: number` - - `"1d"` + The Unix timestamp (in seconds) of when the invite was sent. -- `end_time: optional number` + - `email: string` - End time (Unix seconds) of the query time range, exclusive. + The email address of the individual to whom the invite was sent -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 3 more` + - `object: "organization.invite"` - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `size`, `source` or any combination of them. + The object type, which is always `organization.invite` - - `"project_id"` + - `"organization.invite"` - - `"user_id"` + - `projects: array of object { id, role }` - - `"api_key_id"` + The projects that were granted membership upon acceptance of the invite. - - `"model"` + - `id: string` - - `"size"` + Project's public ID - - `"source"` + - `role: "member" or "owner"` -- `limit: optional number` + Project membership role - Specifies the number of buckets to return. + - `"member"` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + - `"owner"` -- `models: optional array of string` + - `role: "owner" or "reader"` - Return only usage for these models. + `owner` or `reader` -- `page: optional string` + - `"owner"` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + - `"reader"` -- `project_ids: optional array of string` + - `status: "accepted" or "expired" or "pending"` - Return only usage for these projects. + `accepted`,`expired`, or `pending` -- `sizes: optional array of "256x256" or "512x512" or "1024x1024" or 2 more` + - `"accepted"` - Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them. + - `"expired"` - - `"256x256"` + - `"pending"` - - `"512x512"` + - `accepted_at: optional number` - - `"1024x1024"` + The Unix timestamp (in seconds) of when the invite was accepted. - - `"1792x1792"` + - `expires_at: optional number` - - `"1024x1792"` + The Unix timestamp (in seconds) of when the invite expires. -- `sources: optional array of "image.generation" or "image.edit" or "image.variation"` +### Example - Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them. +```http +curl https://api.openai.com/v1/organization/invites/$INVITE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"image.generation"` +#### Response - - `"image.edit"` +```json +{ + "id": "id", + "created_at": 0, + "email": "email", + "object": "organization.invite", + "projects": [ + { + "id": "id", + "role": "member" + } + ], + "role": "owner", + "status": "accepted", + "accepted_at": 0, + "expires_at": 0 +} +``` - - `"image.variation"` +### Example -- `user_ids: optional array of string` +```http +curl https://api.openai.com/v1/organization/invites/invite-abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - Return only usage for these users. +#### Response -### Returns +```json +{ + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "created_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533 +} +``` -- `data: array of object { end_time, object, results, start_time }` +## Domain Types - - `end_time: number` +### Invite - - `object: "bucket"` +- `Invite object { id, created_at, email, 6 more }` - - `"bucket"` + Represents an individual `invite` to the organization. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `id: string` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + The identifier, which can be referenced in API endpoints - The aggregated completions usage details of the specific time bucket. + - `created_at: number` - - `input_tokens: number` + The Unix timestamp (in seconds) of when the invite was sent. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `email: string` - - `num_model_requests: number` + The email address of the individual to whom the invite was sent - The count of requests made to the model. + - `object: "organization.invite"` - - `object: "organization.usage.completions.result"` + The object type, which is always `organization.invite` - - `"organization.usage.completions.result"` + - `"organization.invite"` - - `output_tokens: number` + - `projects: array of object { id, role }` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The projects that were granted membership upon acceptance of the invite. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Project's public ID - - `batch: optional boolean` + - `role: "member" or "owner"` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + Project membership role - - `input_audio_tokens: optional number` + - `"member"` - The aggregated number of uncached audio input tokens used. + - `"owner"` - - `input_cache_write_tokens: optional number` + - `role: "owner" or "reader"` - The aggregated number of input tokens written to the cache. + `owner` or `reader` - - `input_cached_audio_tokens: optional number` + - `"owner"` - The aggregated number of cached audio input tokens used. + - `"reader"` - - `input_cached_image_tokens: optional number` + - `status: "accepted" or "expired" or "pending"` - The aggregated number of cached image input tokens used. + `accepted`,`expired`, or `pending` - - `input_cached_text_tokens: optional number` + - `"accepted"` - The aggregated number of cached text input tokens used. + - `"expired"` - - `input_cached_tokens: optional number` + - `"pending"` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `accepted_at: optional number` - - `input_image_tokens: optional number` + The Unix timestamp (in seconds) of when the invite was accepted. - The aggregated number of uncached image input tokens used. + - `expires_at: optional number` - - `input_text_tokens: optional number` + The Unix timestamp (in seconds) of when the invite expires. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +### Invite Delete Response - - `input_uncached_tokens: optional number` +- `InviteDeleteResponse object { id, deleted, object }` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + - `id: string` - - `model: optional string` + - `deleted: boolean` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "organization.invite.deleted"` - - `output_audio_tokens: optional number` + The object type, which is always `organization.invite.deleted` - The aggregated number of audio output tokens used. + - `"organization.invite.deleted"` - - `output_image_tokens: optional number` +# Projects - The aggregated number of image output tokens used. +## Archive project - - `output_text_tokens: optional number` +**post** `/organization/projects/{project_id}/archive` - The aggregated number of text output tokens used. +Archives a project in the organization. Archived projects cannot be used or updated. - - `project_id: optional string` +### Path Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `project_id: string` - - `service_tier: optional string` +### Returns - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +- `Project object { id, created_at, object, 4 more }` - - `user_id: optional string` + Represents an individual project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + The identifier, which can be referenced in API endpoints - The aggregated embeddings usage details of the specific time bucket. + - `created_at: number` - - `input_tokens: number` + The Unix timestamp (in seconds) of when the project was created. - The aggregated number of input tokens used. + - `object: "organization.project"` - - `num_model_requests: number` + The object type, which is always `organization.project` - The count of requests made to the model. + - `"organization.project"` - - `object: "organization.usage.embeddings.result"` + - `archived_at: optional number` - - `"organization.usage.embeddings.result"` + The Unix timestamp (in seconds) of when the project was archived or `null`. - - `api_key_id: optional string` + - `external_key_id: optional string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The external key associated with the project. - - `model: optional string` + - `name: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + The name of the project. This appears in reporting. - - `project_id: optional string` + - `status: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + `active` or `archived` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/archive \ + -X POST \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +#### Response - The aggregated moderations usage details of the specific time bucket. +```json +{ + "id": "id", + "created_at": 0, + "object": "organization.project", + "archived_at": 0, + "external_key_id": "external_key_id", + "name": "name", + "status": "status" +} +``` - - `input_tokens: number` +### Example - The aggregated number of input tokens used. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `num_model_requests: number` +#### Response - The count of requests made to the model. +```json +{ + "id": "proj_abc", + "object": "organization.project", + "name": "Project DEF", + "created_at": 1711471533, + "archived_at": 1711471533, + "status": "archived" +} +``` - - `object: "organization.usage.moderations.result"` +## Create project - - `"organization.usage.moderations.result"` +**post** `/organization/projects` - - `api_key_id: optional string` +Create a new project in the organization. Projects can be created and archived, but cannot be deleted. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Body Parameters - - `model: optional string` +- `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + The friendly name of the project, this name appears in reports. - - `project_id: optional string` +- `external_key_id: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + External key ID to associate with the project. - - `user_id: optional string` +- `geography: optional string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Create the project with the specified data residency region. Your organization must have access to Data residency functionality in order to use. See [data residency controls](/docs/guides/your-data#data-residency-controls) to review the functionality and limitations of setting this field. - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +### Returns - The aggregated images usage details of the specific time bucket. +- `Project object { id, created_at, object, 4 more }` - - `images: number` + Represents an individual project. - The number of images processed. + - `id: string` - - `num_model_requests: number` + The identifier, which can be referenced in API endpoints - The count of requests made to the model. + - `created_at: number` - - `object: "organization.usage.images.result"` + The Unix timestamp (in seconds) of when the project was created. - - `"organization.usage.images.result"` + - `object: "organization.project"` - - `api_key_id: optional string` + The object type, which is always `organization.project` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"organization.project"` - - `model: optional string` + - `archived_at: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The Unix timestamp (in seconds) of when the project was archived or `null`. - - `project_id: optional string` + - `external_key_id: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The external key associated with the project. - - `size: optional string` + - `name: optional string` - When `group_by=size`, this field provides the image size of the grouped usage result. + The name of the project. This appears in reporting. - - `source: optional string` + - `status: optional string` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + `active` or `archived` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "name": "name" + }' +``` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +#### Response - The aggregated audio speeches usage details of the specific time bucket. +```json +{ + "id": "id", + "created_at": 0, + "object": "organization.project", + "archived_at": 0, + "external_key_id": "external_key_id", + "name": "name", + "status": "status" +} +``` - - `characters: number` +### Example - The number of characters processed. +```http +curl -X POST https://api.openai.com/v1/organization/projects \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Project ABC" + }' +``` - - `num_model_requests: number` +#### Response - The count of requests made to the model. +```json +{ + "id": "proj_abc", + "object": "organization.project", + "name": "Project ABC", + "created_at": 1711471533, + "archived_at": null, + "status": "active" +} +``` - - `object: "organization.usage.audio_speeches.result"` +## List projects - - `"organization.usage.audio_speeches.result"` +**get** `/organization/projects` - - `api_key_id: optional string` +Returns a list of projects. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Query Parameters - - `model: optional string` +- `after: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `project_id: optional string` +- `include_archived: optional boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + If `true` returns all projects including those that have been `archived`. Archived projects are not included by default. - - `user_id: optional string` +- `limit: optional number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +### Returns - The aggregated audio transcriptions usage details of the specific time bucket. +- `data: array of Project` - - `num_model_requests: number` + - `id: string` - The count of requests made to the model. + The identifier, which can be referenced in API endpoints - - `object: "organization.usage.audio_transcriptions.result"` + - `created_at: number` - - `"organization.usage.audio_transcriptions.result"` + The Unix timestamp (in seconds) of when the project was created. - - `seconds: number` + - `object: "organization.project"` - The number of seconds processed. + The object type, which is always `organization.project` - - `api_key_id: optional string` + - `"organization.project"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `archived_at: optional number` - - `model: optional string` + The Unix timestamp (in seconds) of when the project was archived or `null`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `external_key_id: optional string` - - `project_id: optional string` + The external key associated with the project. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `name: optional string` - - `user_id: optional string` + The name of the project. This appears in reporting. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `status: optional string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + `active` or `archived` - The aggregated vector stores usage details of the specific time bucket. +- `has_more: boolean` - - `object: "organization.usage.vector_stores.result"` +- `object: "list"` - - `"organization.usage.vector_stores.result"` + - `"list"` - - `usage_bytes: number` +- `first_id: optional string` - The vector stores usage in bytes. +- `last_id: optional string` - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +#### Response - The aggregated code interpreter sessions usage details of the specific time bucket. +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "object": "organization.project", + "archived_at": 0, + "external_key_id": "external_key_id", + "name": "name", + "status": "status" + } + ], + "has_more": true, + "object": "list", + "first_id": "first_id", + "last_id": "last_id" +} +``` - - `num_sessions: number` +### Example - The number of code interpreter sessions. +```http +curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.code_interpreter_sessions.result"` +#### Response - - `"organization.usage.code_interpreter_sessions.result"` +```json +{ + "object": "list", + "data": [ + { + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" + } + ], + "first_id": "proj-abc", + "last_id": "proj-xyz", + "has_more": false +} +``` - - `project_id: optional string` +## Retrieve project - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**get** `/organization/projects/{project_id}` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +Retrieves a project. - The aggregated file search calls usage details of the specific time bucket. +### Path Parameters - - `num_requests: number` +- `project_id: string` - The count of file search calls. +### Returns - - `object: "organization.usage.file_searches.result"` +- `Project object { id, created_at, object, 4 more }` - - `"organization.usage.file_searches.result"` + Represents an individual project. - - `api_key_id: optional string` + - `id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `project_id: optional string` + - `created_at: number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The Unix timestamp (in seconds) of when the project was created. - - `user_id: optional string` + - `object: "organization.project"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The object type, which is always `organization.project` - - `vector_store_id: optional string` + - `"organization.project"` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `archived_at: optional number` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + The Unix timestamp (in seconds) of when the project was archived or `null`. - The aggregated web search calls usage details of the specific time bucket. + - `external_key_id: optional string` - - `num_model_requests: number` + The external key associated with the project. - The count of model requests. + - `name: optional string` - - `num_requests: number` + The name of the project. This appears in reporting. - The count of web search calls. + - `status: optional string` - - `object: "organization.usage.web_searches.result"` + `active` or `archived` - - `"organization.usage.web_searches.result"` +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `context_level: optional string` +```json +{ + "id": "id", + "created_at": 0, + "object": "organization.project", + "archived_at": 0, + "external_key_id": "external_key_id", + "name": "name", + "status": "status" +} +``` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +### Example - - `model: optional string` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## Modify project - - `user_id: optional string` +**post** `/organization/projects/{project_id}` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Modifies a project in the organization. - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +### Path Parameters - The aggregated costs details of the specific time bucket. +- `project_id: string` - - `object: "organization.costs.result"` +### Body Parameters - - `"organization.costs.result"` +- `external_key_id: optional string` - - `amount: optional object { currency, value }` + External key ID to associate with the project. - The monetary value in its associated currency. +- `geography: optional string` - - `currency: optional string` + Geography for the project. - Lowercase ISO-4217 currency e.g. "usd" +- `name: optional string` - - `value: optional number` + The updated name of the project, this name appears in reports. - The numeric value of the cost. +### Returns - - `api_key_id: optional string` +- `Project object { id, created_at, object, 4 more }` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + Represents an individual project. - - `line_item: optional string` + - `id: string` - When `group_by=line_item`, this field provides the line item of the grouped costs result. + The identifier, which can be referenced in API endpoints - - `project_id: optional string` + - `created_at: number` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + The Unix timestamp (in seconds) of when the project was created. - - `quantity: optional number` + - `object: "organization.project"` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + The object type, which is always `organization.project` - - `start_time: number` + - `"organization.project"` -- `has_more: boolean` + - `archived_at: optional number` -- `next_page: string` + The Unix timestamp (in seconds) of when the project was archived or `null`. -- `object: "page"` + - `external_key_id: optional string` - - `"page"` + The external key associated with the project. -### Example + - `name: optional string` -```http -curl https://api.openai.com/v1/organization/usage/images \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The name of the project. This appears in reporting. -#### Response + - `status: optional string` -```json -{ - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" -} -``` + `active` or `archived` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.images.result", - "images": 2, - "num_model_requests": 2, - "size": null, - "source": null, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] - } - ], - "has_more": false, - "next_page": null -} -``` - -## Moderations - -**get** `/organization/usage/moderations` - -Get moderations usage details for the organization. - -### Query Parameters - -- `start_time: number` - - Start time (Unix seconds) of the query time range, inclusive. - -- `api_key_ids: optional array of string` - - Return only usage for these API keys. - -- `bucket_width: optional "1m" or "1h" or "1d"` - - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - - `"1m"` - - - `"1h"` - - - `"1d"` + "id": "id", + "created_at": 0, + "object": "organization.project", + "archived_at": 0, + "external_key_id": "external_key_id", + "name": "name", + "status": "status" +} +``` -- `end_time: optional number` +### Example - End time (Unix seconds) of the query time range, exclusive. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Project DEF" + }' +``` -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` +## Domain Types - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. +### Project - - `"project_id"` +- `Project object { id, created_at, object, 4 more }` - - `"user_id"` + Represents an individual project. - - `"api_key_id"` + - `id: string` - - `"model"` + The identifier, which can be referenced in API endpoints -- `limit: optional number` + - `created_at: number` - Specifies the number of buckets to return. + The Unix timestamp (in seconds) of when the project was created. - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + - `object: "organization.project"` -- `models: optional array of string` + The object type, which is always `organization.project` - Return only usage for these models. + - `"organization.project"` -- `page: optional string` + - `archived_at: optional number` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + The Unix timestamp (in seconds) of when the project was archived or `null`. -- `project_ids: optional array of string` + - `external_key_id: optional string` - Return only usage for these projects. + The external key associated with the project. -- `user_ids: optional array of string` + - `name: optional string` - Return only usage for these users. + The name of the project. This appears in reporting. -### Returns + - `status: optional string` -- `data: array of object { end_time, object, results, start_time }` + `active` or `archived` - - `end_time: number` +# API Keys - - `object: "bucket"` +## Delete project API key - - `"bucket"` +**delete** `/organization/projects/{project_id}/api_keys/{api_key_id}` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +Deletes an API key from the project. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +Returns confirmation of the key deletion, or an error if the key belonged to +a service account. - The aggregated completions usage details of the specific time bucket. +### Path Parameters - - `input_tokens: number` +- `project_id: string` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `api_key_id: string` - - `num_model_requests: number` +### Returns - The count of requests made to the model. +- `id: string` - - `object: "organization.usage.completions.result"` +- `deleted: boolean` - - `"organization.usage.completions.result"` +- `object: "organization.project.api_key.deleted"` - - `output_tokens: number` + - `"organization.project.api_key.deleted"` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys/$API_KEY_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `batch: optional boolean` +```json +{ + "id": "id", + "deleted": true, + "object": "organization.project.api_key.deleted" +} +``` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +### Example - - `input_audio_tokens: optional number` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated number of uncached audio input tokens used. +#### Response - - `input_cache_write_tokens: optional number` +```json +{ + "object": "organization.project.api_key.deleted", + "id": "key_abc", + "deleted": true +} +``` - The aggregated number of input tokens written to the cache. +## List project API keys - - `input_cached_audio_tokens: optional number` +**get** `/organization/projects/{project_id}/api_keys` - The aggregated number of cached audio input tokens used. +Returns a list of API keys in the project. - - `input_cached_image_tokens: optional number` +### Path Parameters - The aggregated number of cached image input tokens used. +- `project_id: string` - - `input_cached_text_tokens: optional number` +### Query Parameters - The aggregated number of cached text input tokens used. +- `after: optional string` - - `input_cached_tokens: optional number` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `limit: optional number` - - `input_image_tokens: optional number` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The aggregated number of uncached image input tokens used. +- `owner_project_access: optional "active" or "inactive" or "any"` - - `input_text_tokens: optional number` + Filter API keys by whether the owner currently has effective access to the project. Use `active` for owners with access, `inactive` for owners without access, or `any` for all enabled project API keys. If omitted, the endpoint applies its existing membership-based visibility rules, which may exclude some enabled keys. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `"active"` - - `input_uncached_tokens: optional number` + - `"inactive"` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + - `"any"` - - `model: optional string` +### Returns - When `group_by=model`, this field provides the model name of the grouped usage result. +- `data: array of ProjectAPIKey` - - `output_audio_tokens: optional number` + - `id: string` - The aggregated number of audio output tokens used. + The identifier, which can be referenced in API endpoints - - `output_image_tokens: optional number` + - `created_at: number` - The aggregated number of image output tokens used. + The Unix timestamp (in seconds) of when the API key was created - - `output_text_tokens: optional number` + - `last_used_at: number` - The aggregated number of text output tokens used. + The Unix timestamp (in seconds) of when the API key was last used. - - `project_id: optional string` + - `name: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The name of the API key - - `service_tier: optional string` + - `object: "organization.project.api_key"` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + The object type, which is always `organization.project.api_key` - - `user_id: optional string` + - `"organization.project.api_key"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `owner: object { service_account, type, user }` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + - `service_account: optional object { id, created_at, name, role }` - The aggregated embeddings usage details of the specific time bucket. + The service account that owns a project API key. - - `input_tokens: number` + - `id: string` - The aggregated number of input tokens used. + The identifier, which can be referenced in API endpoints - - `num_model_requests: number` + - `created_at: number` - The count of requests made to the model. + The Unix timestamp (in seconds) of when the service account was created. - - `object: "organization.usage.embeddings.result"` + - `name: string` - - `"organization.usage.embeddings.result"` + The name of the service account. - - `api_key_id: optional string` + - `role: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The service account's project role. - - `model: optional string` + - `type: optional "user" or "service_account"` - When `group_by=model`, this field provides the model name of the grouped usage result. + `user` or `service_account` - - `project_id: optional string` + - `"user"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"service_account"` - - `user_id: optional string` + - `user: optional object { id, created_at, email, 2 more }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The user that owns a project API key. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `id: string` - The aggregated moderations usage details of the specific time bucket. + The identifier, which can be referenced in API endpoints - - `input_tokens: number` + - `created_at: number` - The aggregated number of input tokens used. + The Unix timestamp (in seconds) of when the user was created. - - `num_model_requests: number` + - `email: string` - The count of requests made to the model. + The email address of the user. - - `object: "organization.usage.moderations.result"` + - `name: string` - - `"organization.usage.moderations.result"` + The name of the user. - - `api_key_id: optional string` + - `role: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The user's project role. - - `model: optional string` + - `owner_project_access: "active" or "inactive"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the API key's owner currently has effective access to the project. - - `project_id: optional string` + - `"active"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"inactive"` - - `user_id: optional string` + - `redacted_value: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The redacted value of the API key - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +- `has_more: boolean` - The aggregated images usage details of the specific time bucket. +- `object: "list"` - - `images: number` + - `"list"` - The number of images processed. +- `first_id: optional string` - - `num_model_requests: number` +- `last_id: optional string` - The count of requests made to the model. +### Example - - `object: "organization.usage.images.result"` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"organization.usage.images.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "last_used_at": 0, + "name": "name", + "object": "organization.project.api_key", + "owner": { + "service_account": { + "id": "id", + "created_at": 0, + "name": "name", + "role": "role" + }, + "type": "user", + "user": { + "id": "id", + "created_at": 0, + "email": "email", + "name": "name", + "role": "role" + } + }, + "owner_project_access": "active", + "redacted_value": "redacted_value" + } + ], + "has_more": true, + "object": "list", + "first_id": "first_id", + "last_id": "last_id" +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `model: optional string` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20&owner_project_access=any \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "object": "list", + "data": [ + { + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "last_used_at": 1711471534, + "id": "key_abc", + "owner_project_access": "active", + "owner": { + "type": "user", + "user": { + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "created_at": 1711471533 + } + } + } + ], + "first_id": "key_abc", + "last_id": "key_xyz", + "has_more": false +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## Retrieve project API key - - `size: optional string` +**get** `/organization/projects/{project_id}/api_keys/{api_key_id}` - When `group_by=size`, this field provides the image size of the grouped usage result. +Retrieves an API key in the project. - - `source: optional string` +### Path Parameters - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. +- `project_id: string` - - `user_id: optional string` +- `api_key_id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Returns - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +- `ProjectAPIKey object { id, created_at, last_used_at, 5 more }` - The aggregated audio speeches usage details of the specific time bucket. + Represents an individual API key in a project. - - `characters: number` + - `id: string` - The number of characters processed. + The identifier, which can be referenced in API endpoints - - `num_model_requests: number` + - `created_at: number` - The count of requests made to the model. + The Unix timestamp (in seconds) of when the API key was created - - `object: "organization.usage.audio_speeches.result"` + - `last_used_at: number` - - `"organization.usage.audio_speeches.result"` + The Unix timestamp (in seconds) of when the API key was last used. - - `api_key_id: optional string` + - `name: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The name of the API key - - `model: optional string` + - `object: "organization.project.api_key"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The object type, which is always `organization.project.api_key` - - `project_id: optional string` + - `"organization.project.api_key"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `owner: object { service_account, type, user }` - - `user_id: optional string` + - `service_account: optional object { id, created_at, name, role }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The service account that owns a project API key. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `id: string` - The aggregated audio transcriptions usage details of the specific time bucket. + The identifier, which can be referenced in API endpoints - - `num_model_requests: number` + - `created_at: number` - The count of requests made to the model. + The Unix timestamp (in seconds) of when the service account was created. - - `object: "organization.usage.audio_transcriptions.result"` + - `name: string` - - `"organization.usage.audio_transcriptions.result"` + The name of the service account. - - `seconds: number` + - `role: string` - The number of seconds processed. + The service account's project role. - - `api_key_id: optional string` + - `type: optional "user" or "service_account"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + `user` or `service_account` - - `model: optional string` + - `"user"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"service_account"` - - `project_id: optional string` + - `user: optional object { id, created_at, email, 2 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The user that owns a project API key. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + - `created_at: number` - The aggregated vector stores usage details of the specific time bucket. + The Unix timestamp (in seconds) of when the user was created. - - `object: "organization.usage.vector_stores.result"` + - `email: string` - - `"organization.usage.vector_stores.result"` + The email address of the user. - - `usage_bytes: number` + - `name: string` - The vector stores usage in bytes. + The name of the user. - - `project_id: optional string` + - `role: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The user's project role. - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `owner_project_access: "active" or "inactive"` - The aggregated code interpreter sessions usage details of the specific time bucket. + Whether the API key's owner currently has effective access to the project. - - `num_sessions: number` + - `"active"` - The number of code interpreter sessions. + - `"inactive"` - - `object: "organization.usage.code_interpreter_sessions.result"` + - `redacted_value: string` - - `"organization.usage.code_interpreter_sessions.result"` + The redacted value of the API key - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys/$API_KEY_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +#### Response - The aggregated file search calls usage details of the specific time bucket. +```json +{ + "id": "id", + "created_at": 0, + "last_used_at": 0, + "name": "name", + "object": "organization.project.api_key", + "owner": { + "service_account": { + "id": "id", + "created_at": 0, + "name": "name", + "role": "role" + }, + "type": "user", + "user": { + "id": "id", + "created_at": 0, + "email": "email", + "name": "name", + "role": "role" + } + }, + "owner_project_access": "active", + "redacted_value": "redacted_value" +} +``` - - `num_requests: number` +### Example - The count of file search calls. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.file_searches.result"` +#### Response - - `"organization.usage.file_searches.result"` +```json +{ + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "last_used_at": 1711471534, + "id": "key_abc", + "owner_project_access": "active", + "owner": { + "type": "user", + "user": { + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "created_at": 1711471533 + } + } +} +``` - - `api_key_id: optional string` +## Domain Types - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### API Key Delete Response - - `project_id: optional string` +- `APIKeyDeleteResponse object { id, deleted, object }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `id: string` - - `user_id: optional string` + - `deleted: boolean` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `object: "organization.project.api_key.deleted"` - - `vector_store_id: optional string` + - `"organization.project.api_key.deleted"` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +### Project API Key - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +- `ProjectAPIKey object { id, created_at, last_used_at, 5 more }` - The aggregated web search calls usage details of the specific time bucket. + Represents an individual API key in a project. - - `num_model_requests: number` + - `id: string` - The count of model requests. + The identifier, which can be referenced in API endpoints - - `num_requests: number` + - `created_at: number` - The count of web search calls. + The Unix timestamp (in seconds) of when the API key was created - - `object: "organization.usage.web_searches.result"` + - `last_used_at: number` - - `"organization.usage.web_searches.result"` + The Unix timestamp (in seconds) of when the API key was last used. - - `api_key_id: optional string` + - `name: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The name of the API key - - `context_level: optional string` + - `object: "organization.project.api_key"` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + The object type, which is always `organization.project.api_key` - - `model: optional string` + - `"organization.project.api_key"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `owner: object { service_account, type, user }` - - `project_id: optional string` + - `service_account: optional object { id, created_at, name, role }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The service account that owns a project API key. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `created_at: number` - The aggregated costs details of the specific time bucket. + The Unix timestamp (in seconds) of when the service account was created. - - `object: "organization.costs.result"` + - `name: string` - - `"organization.costs.result"` + The name of the service account. - - `amount: optional object { currency, value }` + - `role: string` - The monetary value in its associated currency. + The service account's project role. - - `currency: optional string` + - `type: optional "user" or "service_account"` - Lowercase ISO-4217 currency e.g. "usd" + `user` or `service_account` - - `value: optional number` + - `"user"` - The numeric value of the cost. + - `"service_account"` - - `api_key_id: optional string` + - `user: optional object { id, created_at, email, 2 more }` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + The user that owns a project API key. - - `line_item: optional string` + - `id: string` - When `group_by=line_item`, this field provides the line item of the grouped costs result. + The identifier, which can be referenced in API endpoints - - `project_id: optional string` + - `created_at: number` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + The Unix timestamp (in seconds) of when the user was created. - - `quantity: optional number` + - `email: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + The email address of the user. - - `start_time: number` + - `name: string` -- `has_more: boolean` + The name of the user. -- `next_page: string` + - `role: string` -- `object: "page"` + The user's project role. - - `"page"` + - `owner_project_access: "active" or "inactive"` -### Example + Whether the API key's owner currently has effective access to the project. -```http -curl https://api.openai.com/v1/organization/usage/moderations \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"active"` -#### Response + - `"inactive"` -```json -{ - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" -} -``` + - `redacted_value: string` -### Example + The redacted value of the API key -```http -curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" -``` +# Certificates -#### Response +## Activate certificates for project -```json -{ - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.moderations.result", - "input_tokens": 16, - "num_model_requests": 2, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null - } - ] - } - ], - "has_more": false, - "next_page": null -} -``` +**post** `/organization/projects/{project_id}/certificates/activate` -## Vector stores +Activate certificates at the project level. -**get** `/organization/usage/vector_stores` +You can atomically and idempotently activate up to 10 certificates at a time. -Get vector stores usage details for the organization. +### Path Parameters -### Query Parameters +- `project_id: string` -- `start_time: number` +### Body Parameters - Start time (Unix seconds) of the query time range, inclusive. +- `certificate_ids: array of string` -- `bucket_width: optional "1m" or "1h" or "1d"` +### Returns - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. +- `data: array of object { id, active, certificate_details, 3 more }` - - `"1m"` + - `id: string` - - `"1h"` + The identifier, which can be referenced in API endpoints - - `"1d"` + - `active: boolean` -- `end_time: optional number` + Whether the certificate is currently active at the project level. - End time (Unix seconds) of the query time range, exclusive. + - `certificate_details: object { expires_at, valid_at }` -- `group_by: optional array of "project_id"` + - `expires_at: optional number` - Group the usage data by the specified fields. Support fields include `project_id`. + The Unix timestamp (in seconds) of when the certificate expires. - - `"project_id"` + - `valid_at: optional number` -- `limit: optional number` + The Unix timestamp (in seconds) of when the certificate becomes valid. - Specifies the number of buckets to return. + - `created_at: number` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + The Unix timestamp (in seconds) of when the certificate was uploaded. -- `page: optional string` + - `name: string` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + The name of the certificate. -- `project_ids: optional array of string` + - `object: "organization.project.certificate"` - Return only usage for these projects. + The object type, which is always `organization.project.certificate`. -### Returns + - `"organization.project.certificate"` -- `data: array of object { end_time, object, results, start_time }` +- `object: "organization.project.certificate.activation"` - - `end_time: number` + The project certificate activation result type. - - `object: "bucket"` + - `"organization.project.certificate.activation"` - - `"bucket"` +### Example - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates/activate \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "certificate_ids": [ + "cert_abc" + ] + }' +``` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +#### Response - The aggregated completions usage details of the specific time bucket. +```json +{ + "data": [ + { + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.project.certificate" + } + ], + "object": "organization.project.certificate.activation" +} +``` - - `input_tokens: number` +### Example - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "certificate_ids": ["cert_abc", "cert_def"] +}' +``` - - `num_model_requests: number` +#### Response - The count of requests made to the model. +```json +{ + "object": "organization.project.certificate.activation", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.project.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], +} +``` - - `object: "organization.usage.completions.result"` +## Deactivate certificates for project - - `"organization.usage.completions.result"` +**post** `/organization/projects/{project_id}/certificates/deactivate` - - `output_tokens: number` +Deactivate certificates at the project level. You can atomically and +idempotently deactivate up to 10 certificates at a time. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Path Parameters - - `api_key_id: optional string` +- `project_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Body Parameters - - `batch: optional boolean` +- `certificate_ids: array of string` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +### Returns - - `input_audio_tokens: optional number` +- `data: array of object { id, active, certificate_details, 3 more }` - The aggregated number of uncached audio input tokens used. + - `id: string` - - `input_cache_write_tokens: optional number` + The identifier, which can be referenced in API endpoints - The aggregated number of input tokens written to the cache. + - `active: boolean` - - `input_cached_audio_tokens: optional number` + Whether the certificate is currently active at the project level. - The aggregated number of cached audio input tokens used. + - `certificate_details: object { expires_at, valid_at }` - - `input_cached_image_tokens: optional number` + - `expires_at: optional number` - The aggregated number of cached image input tokens used. + The Unix timestamp (in seconds) of when the certificate expires. - - `input_cached_text_tokens: optional number` + - `valid_at: optional number` - The aggregated number of cached text input tokens used. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `input_cached_tokens: optional number` + - `created_at: number` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `input_image_tokens: optional number` + - `name: string` - The aggregated number of uncached image input tokens used. + The name of the certificate. - - `input_text_tokens: optional number` + - `object: "organization.project.certificate"` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + The object type, which is always `organization.project.certificate`. - - `input_uncached_tokens: optional number` + - `"organization.project.certificate"` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +- `object: "organization.project.certificate.deactivation"` - - `model: optional string` + The project certificate deactivation result type. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"organization.project.certificate.deactivation"` - - `output_audio_tokens: optional number` +### Example - The aggregated number of audio output tokens used. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates/deactivate \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "certificate_ids": [ + "cert_abc" + ] + }' +``` - - `output_image_tokens: optional number` +#### Response - The aggregated number of image output tokens used. +```json +{ + "data": [ + { + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.project.certificate" + } + ], + "object": "organization.project.certificate.deactivation" +} +``` - - `output_text_tokens: optional number` +### Example - The aggregated number of text output tokens used. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" \ +-d '{ + "certificate_ids": ["cert_abc", "cert_def"] +}' +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```json +{ + "object": "organization.project.certificate.deactivation", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + { + "object": "organization.project.certificate", + "id": "cert_def", + "name": "My Example Certificate 2", + "active": false, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], +} +``` - - `service_tier: optional string` +## List project certificates - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +**get** `/organization/projects/{project_id}/certificates` - - `user_id: optional string` +List certificates for this project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Path Parameters - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +- `project_id: string` - The aggregated embeddings usage details of the specific time bucket. +### Query Parameters - - `input_tokens: number` +- `after: optional string` - The aggregated number of input tokens used. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `num_model_requests: number` +- `limit: optional number` - The count of requests made to the model. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `object: "organization.usage.embeddings.result"` +- `order: optional "asc" or "desc"` - - `"organization.usage.embeddings.result"` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `api_key_id: optional string` + - `"asc"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"desc"` - - `model: optional string` +### Returns - When `group_by=model`, this field provides the model name of the grouped usage result. +- `data: array of object { id, active, certificate_details, 3 more }` - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `user_id: optional string` + - `active: boolean` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Whether the certificate is currently active at the project level. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `certificate_details: object { expires_at, valid_at }` - The aggregated moderations usage details of the specific time bucket. + - `expires_at: optional number` - - `input_tokens: number` + The Unix timestamp (in seconds) of when the certificate expires. - The aggregated number of input tokens used. + - `valid_at: optional number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of when the certificate becomes valid. - The count of requests made to the model. + - `created_at: number` - - `object: "organization.usage.moderations.result"` + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `"organization.usage.moderations.result"` + - `name: string` - - `api_key_id: optional string` + The name of the certificate. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `object: "organization.project.certificate"` - - `model: optional string` + The object type, which is always `organization.project.certificate`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"organization.project.certificate"` - - `project_id: optional string` +- `first_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `has_more: boolean` - - `user_id: optional string` +- `last_id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `object: "list"` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + - `"list"` - The aggregated images usage details of the specific time bucket. +### Example - - `images: number` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The number of images processed. +#### Response - - `num_model_requests: number` +```json +{ + "data": [ + { + "id": "id", + "active": true, + "certificate_details": { + "expires_at": 0, + "valid_at": 0 + }, + "created_at": 0, + "name": "name", + "object": "organization.project.certificate" + } + ], + "first_id": "cert_abc", + "has_more": true, + "last_id": "cert_abc", + "object": "list" +} +``` - The count of requests made to the model. +### Example - - `object: "organization.usage.images.result"` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"organization.usage.images.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "object": "list", + "data": [ + { + "object": "organization.project.certificate", + "id": "cert_abc", + "name": "My Example Certificate", + "active": true, + "created_at": 1234567, + "certificate_details": { + "valid_at": 12345667, + "expires_at": 12345678 + } + }, + ], + "first_id": "cert_abc", + "last_id": "cert_abc", + "has_more": false +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +## Domain Types - - `model: optional string` +### Certificate Activate Response - When `group_by=model`, this field provides the model name of the grouped usage result. +- `CertificateActivateResponse object { id, active, certificate_details, 3 more }` - - `project_id: optional string` + Represents an individual certificate configured at the project level. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `id: string` - - `size: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=size`, this field provides the image size of the grouped usage result. + - `active: boolean` - - `source: optional string` + Whether the certificate is currently active at the project level. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `certificate_details: object { expires_at, valid_at }` - - `user_id: optional string` + - `expires_at: optional number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate expires. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `valid_at: optional number` - The aggregated audio speeches usage details of the specific time bucket. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `characters: number` + - `created_at: number` - The number of characters processed. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `num_model_requests: number` + - `name: string` - The count of requests made to the model. + The name of the certificate. - - `object: "organization.usage.audio_speeches.result"` + - `object: "organization.project.certificate"` - - `"organization.usage.audio_speeches.result"` + The object type, which is always `organization.project.certificate`. - - `api_key_id: optional string` + - `"organization.project.certificate"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Certificate Deactivate Response - - `model: optional string` +- `CertificateDeactivateResponse object { id, active, certificate_details, 3 more }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Represents an individual certificate configured at the project level. - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `user_id: optional string` + - `active: boolean` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Whether the certificate is currently active at the project level. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `certificate_details: object { expires_at, valid_at }` - The aggregated audio transcriptions usage details of the specific time bucket. + - `expires_at: optional number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of when the certificate expires. - The count of requests made to the model. + - `valid_at: optional number` - - `object: "organization.usage.audio_transcriptions.result"` + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `"organization.usage.audio_transcriptions.result"` + - `created_at: number` - - `seconds: number` + The Unix timestamp (in seconds) of when the certificate was uploaded. - The number of seconds processed. + - `name: string` - - `api_key_id: optional string` + The name of the certificate. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `object: "organization.project.certificate"` - - `model: optional string` + The object type, which is always `organization.project.certificate`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"organization.project.certificate"` - - `project_id: optional string` +### Certificate List Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `CertificateListResponse object { id, active, certificate_details, 3 more }` - - `user_id: optional string` + Represents an individual certificate configured at the project level. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + The identifier, which can be referenced in API endpoints - The aggregated vector stores usage details of the specific time bucket. + - `active: boolean` - - `object: "organization.usage.vector_stores.result"` + Whether the certificate is currently active at the project level. - - `"organization.usage.vector_stores.result"` + - `certificate_details: object { expires_at, valid_at }` - - `usage_bytes: number` + - `expires_at: optional number` - The vector stores usage in bytes. + The Unix timestamp (in seconds) of when the certificate expires. - - `project_id: optional string` + - `valid_at: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The Unix timestamp (in seconds) of when the certificate becomes valid. - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `created_at: number` - The aggregated code interpreter sessions usage details of the specific time bucket. + The Unix timestamp (in seconds) of when the certificate was uploaded. - - `num_sessions: number` + - `name: string` - The number of code interpreter sessions. + The name of the certificate. - - `object: "organization.usage.code_interpreter_sessions.result"` + - `object: "organization.project.certificate"` - - `"organization.usage.code_interpreter_sessions.result"` + The object type, which is always `organization.project.certificate`. - - `project_id: optional string` + - `"organization.project.certificate"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +# Data Retention - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +## Retrieve project data retention - The aggregated file search calls usage details of the specific time bucket. +**get** `/organization/projects/{project_id}/data_retention` - - `num_requests: number` +Retrieves project data retention controls. - The count of file search calls. +### Path Parameters - - `object: "organization.usage.file_searches.result"` +- `project_id: string` - - `"organization.usage.file_searches.result"` +### Returns - - `api_key_id: optional string` +- `ProjectDataRetention object { object, type }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Represents a project's data retention control setting. - - `project_id: optional string` + - `object: "project.data_retention"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The object type, which is always `project.data_retention`. - - `user_id: optional string` + - `"project.data_retention"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` - - `vector_store_id: optional string` + The configured project data retention type. - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `"organization_default"` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `"none"` - The aggregated web search calls usage details of the specific time bucket. + - `"zero_data_retention"` - - `num_model_requests: number` + - `"modified_abuse_monitoring"` - The count of model requests. + - `"enhanced_zero_data_retention"` - - `num_requests: number` + - `"enhanced_modified_abuse_monitoring"` - The count of web search calls. +### Example - - `object: "organization.usage.web_searches.result"` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"organization.usage.web_searches.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "object": "project.data_retention", + "type": "organization_default" +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `context_level: optional string` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "object": "project.data_retention", + "type": "organization_default" +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +## Update project data retention - - `project_id: optional string` +**post** `/organization/projects/{project_id}/data_retention` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Updates project data retention controls. - - `user_id: optional string` +### Path Parameters - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `project_id: string` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +### Body Parameters - The aggregated costs details of the specific time bucket. +- `retention_type: "organization_default" or "none" or "zero_data_retention" or 3 more` - - `object: "organization.costs.result"` + The desired project data retention type. - - `"organization.costs.result"` + - `"organization_default"` - - `amount: optional object { currency, value }` + - `"none"` - The monetary value in its associated currency. + - `"zero_data_retention"` - - `currency: optional string` + - `"modified_abuse_monitoring"` - Lowercase ISO-4217 currency e.g. "usd" + - `"enhanced_zero_data_retention"` - - `value: optional number` + - `"enhanced_modified_abuse_monitoring"` - The numeric value of the cost. +### Returns - - `api_key_id: optional string` +- `ProjectDataRetention object { object, type }` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + Represents a project's data retention control setting. - - `line_item: optional string` + - `object: "project.data_retention"` - When `group_by=line_item`, this field provides the line item of the grouped costs result. + The object type, which is always `project.data_retention`. - - `project_id: optional string` + - `"project.data_retention"` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` - - `quantity: optional number` + The configured project data retention type. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `"organization_default"` - - `start_time: number` + - `"none"` -- `has_more: boolean` + - `"zero_data_retention"` -- `next_page: string` + - `"modified_abuse_monitoring"` -- `object: "page"` + - `"enhanced_zero_data_retention"` - - `"page"` + - `"enhanced_modified_abuse_monitoring"` ### Example ```http -curl https://api.openai.com/v1/organization/usage/vector_stores \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/data_retention \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "retention_type": "organization_default" + }' ``` #### Response ```json { - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" + "object": "project.data_retention", + "type": "organization_default" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/data_retention \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "retention_type": "modified_abuse_monitoring" + }' ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.vector_stores.result", - "usage_bytes": 1024, - "project_id": null - } - ] - } - ], - "has_more": false, - "next_page": null + "object": "project.data_retention", + "type": "modified_abuse_monitoring" } ``` -## File search calls +## Domain Types -**get** `/organization/usage/file_search_calls` +### Project Data Retention -Get file search calls usage details for the organization. +- `ProjectDataRetention object { object, type }` -### Query Parameters + Represents a project's data retention control setting. -- `start_time: number` + - `object: "project.data_retention"` - Start time (Unix seconds) of the query time range, inclusive. + The object type, which is always `project.data_retention`. -- `api_key_ids: optional array of string` + - `"project.data_retention"` - Return only usage for these API keys. + - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` -- `bucket_width: optional "1m" or "1h" or "1d"` + The configured project data retention type. - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + - `"organization_default"` - - `"1m"` + - `"none"` - - `"1h"` + - `"zero_data_retention"` - - `"1d"` + - `"modified_abuse_monitoring"` -- `end_time: optional number` + - `"enhanced_zero_data_retention"` - End time (Unix seconds) of the query time range, exclusive. + - `"enhanced_modified_abuse_monitoring"` -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "vector_store_id"` +# Groups - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `vector_store_id` or any combination of them. +## Add project group - - `"project_id"` +**post** `/organization/projects/{project_id}/groups` - - `"user_id"` +Grants a group access to a project. - - `"api_key_id"` +### Path Parameters - - `"vector_store_id"` +- `project_id: string` -- `limit: optional number` +### Body Parameters - Specifies the number of buckets to return. +- `group_id: string` - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 + Identifier of the group to add to the project. -- `page: optional string` +- `role: string` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + Identifier of the project role to grant to the group. -- `project_ids: optional array of string` +### Returns - Return only usage for these projects. +- `ProjectGroup object { created_at, group_id, group_name, 3 more }` -- `user_ids: optional array of string` + Details about a group's membership in a project. - Return only usage for these users. + - `created_at: number` -- `vector_store_ids: optional array of string` + Unix timestamp (in seconds) when the group was granted project access. - Return only usage for these vector stores. + - `group_id: string` -### Returns + Identifier of the group that has access to the project. -- `data: array of object { end_time, object, results, start_time }` + - `group_name: string` - - `end_time: number` + Display name of the group. - - `object: "bucket"` + - `group_type: "group" or "tenant_group"` - - `"bucket"` + The type of the group. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `"group"` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `"tenant_group"` - The aggregated completions usage details of the specific time bucket. + - `object: "project.group"` - - `input_tokens: number` + Always `project.group`. + + - `"project.group"` + + - `project_id: string` + + Identifier of the project. + +### Example + +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "group_id": "group_id", + "role": "role" + }' +``` + +#### Response + +```json +{ + "created_at": 0, + "group_id": "group_id", + "group_name": "group_name", + "group_type": "group", + "object": "project.group", + "project_id": "project_id" +} +``` + +### Example - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc123/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "group_id": "group_01J1F8ABCDXYZ", + "role": "role_01J1F8PROJ" + }' +``` - - `num_model_requests: number` +#### Response - The count of requests made to the model. +```json +{ + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 +} +``` - - `object: "organization.usage.completions.result"` +## Remove project group - - `"organization.usage.completions.result"` +**delete** `/organization/projects/{project_id}/groups/{group_id}` - - `output_tokens: number` +Revokes a group's access to a project. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Path Parameters - - `api_key_id: optional string` +- `project_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `group_id: string` - - `batch: optional boolean` +### Returns - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +- `deleted: boolean` - - `input_audio_tokens: optional number` + Whether the group membership in the project was removed. - The aggregated number of uncached audio input tokens used. +- `object: "project.group.deleted"` - - `input_cache_write_tokens: optional number` + Always `project.group.deleted`. - The aggregated number of input tokens written to the cache. + - `"project.group.deleted"` - - `input_cached_audio_tokens: optional number` +### Example - The aggregated number of cached audio input tokens used. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups/$GROUP_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `input_cached_image_tokens: optional number` +#### Response - The aggregated number of cached image input tokens used. +```json +{ + "deleted": true, + "object": "project.group.deleted" +} +``` - - `input_cached_text_tokens: optional number` +### Example - The aggregated number of cached text input tokens used. +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `input_cached_tokens: optional number` +#### Response - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```json +{ + "object": "project.group.deleted", + "deleted": true +} +``` - - `input_image_tokens: optional number` +## List project groups - The aggregated number of uncached image input tokens used. +**get** `/organization/projects/{project_id}/groups` - - `input_text_tokens: optional number` +Lists the groups that have access to a project. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +### Path Parameters - - `input_uncached_tokens: optional number` +- `project_id: string` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +### Query Parameters - - `model: optional string` +- `after: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Cursor for pagination. Provide the ID of the last group from the previous response to fetch the next page. - - `output_audio_tokens: optional number` +- `limit: optional number` - The aggregated number of audio output tokens used. + A limit on the number of project groups to return. Defaults to 20. - - `output_image_tokens: optional number` +- `order: optional "asc" or "desc"` - The aggregated number of image output tokens used. + Sort order for the returned groups. - - `output_text_tokens: optional number` + - `"asc"` - The aggregated number of text output tokens used. + - `"desc"` - - `project_id: optional string` +### Returns - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `data: array of ProjectGroup` - - `service_tier: optional string` + Project group memberships returned in the current page. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `created_at: number` - - `user_id: optional string` + Unix timestamp (in seconds) when the group was granted project access. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `group_id: string` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + Identifier of the group that has access to the project. - The aggregated embeddings usage details of the specific time bucket. + - `group_name: string` - - `input_tokens: number` + Display name of the group. - The aggregated number of input tokens used. + - `group_type: "group" or "tenant_group"` - - `num_model_requests: number` + The type of the group. - The count of requests made to the model. + - `"group"` - - `object: "organization.usage.embeddings.result"` + - `"tenant_group"` - - `"organization.usage.embeddings.result"` + - `object: "project.group"` - - `api_key_id: optional string` + Always `project.group`. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"project.group"` - - `model: optional string` + - `project_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Identifier of the project. - - `project_id: optional string` +- `has_more: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether additional project group memberships are available. - - `user_id: optional string` +- `next: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Cursor to fetch the next page of results, or `null` when there are no more results. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +- `object: "list"` - The aggregated moderations usage details of the specific time bucket. + Always `list`. - - `input_tokens: number` + - `"list"` - The aggregated number of input tokens used. +### Example - - `num_model_requests: number` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The count of requests made to the model. +#### Response - - `object: "organization.usage.moderations.result"` +```json +{ + "data": [ + { + "created_at": 0, + "group_id": "group_id", + "group_name": "group_name", + "group_type": "group", + "object": "project.group", + "project_id": "project_id" + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `"organization.usage.moderations.result"` +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc123/groups?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "object": "list", + "data": [ + { + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "created_at": 1711471533 + } + ], + "has_more": false, + "next": null +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +## Retrieve project group - - `project_id: optional string` +**get** `/organization/projects/{project_id}/groups/{group_id}` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Retrieves a project's group. - - `user_id: optional string` +### Path Parameters - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `project_id: string` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +- `group_id: string` - The aggregated images usage details of the specific time bucket. +### Query Parameters - - `images: number` +- `group_type: optional "group" or "tenant_group"` - The number of images processed. + The type of group to retrieve. - - `num_model_requests: number` + - `"group"` - The count of requests made to the model. + - `"tenant_group"` - - `object: "organization.usage.images.result"` +### Returns - - `"organization.usage.images.result"` +- `ProjectGroup object { created_at, group_id, group_name, 3 more }` - - `api_key_id: optional string` + Details about a group's membership in a project. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `created_at: number` - - `model: optional string` + Unix timestamp (in seconds) when the group was granted project access. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `group_id: string` - - `project_id: optional string` + Identifier of the group that has access to the project. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `group_name: string` - - `size: optional string` + Display name of the group. - When `group_by=size`, this field provides the image size of the grouped usage result. + - `group_type: "group" or "tenant_group"` - - `source: optional string` + The type of the group. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `"group"` - - `user_id: optional string` + - `"tenant_group"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `object: "project.group"` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + Always `project.group`. - The aggregated audio speeches usage details of the specific time bucket. + - `"project.group"` - - `characters: number` + - `project_id: string` - The number of characters processed. + Identifier of the project. - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups/$GROUP_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `object: "organization.usage.audio_speeches.result"` +#### Response - - `"organization.usage.audio_speeches.result"` +```json +{ + "created_at": 0, + "group_id": "group_id", + "group_name": "group_name", + "group_type": "group", + "object": "project.group", + "project_id": "project_id" +} +``` - - `api_key_id: optional string` +### Example - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `model: optional string` +#### Response - When `group_by=model`, this field provides the model name of the grouped usage result. +```json +{ + "object": "project.group", + "project_id": "proj_abc123", + "group_id": "group_01J1F8ABCDXYZ", + "group_name": "Support Team", + "group_type": "group", + "created_at": 1711471533 +} +``` - - `project_id: optional string` +## Domain Types - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Group Delete Response - - `user_id: optional string` +- `GroupDeleteResponse object { deleted, object }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Confirmation payload returned after removing a group from a project. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `deleted: boolean` - The aggregated audio transcriptions usage details of the specific time bucket. + Whether the group membership in the project was removed. - - `num_model_requests: number` + - `object: "project.group.deleted"` - The count of requests made to the model. + Always `project.group.deleted`. - - `object: "organization.usage.audio_transcriptions.result"` + - `"project.group.deleted"` - - `"organization.usage.audio_transcriptions.result"` +### Project Group - - `seconds: number` +- `ProjectGroup object { created_at, group_id, group_name, 3 more }` - The number of seconds processed. + Details about a group's membership in a project. - - `api_key_id: optional string` + - `created_at: number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Unix timestamp (in seconds) when the group was granted project access. - - `model: optional string` + - `group_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Identifier of the group that has access to the project. - - `project_id: optional string` + - `group_name: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Display name of the group. - - `user_id: optional string` + - `group_type: "group" or "tenant_group"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The type of the group. - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + - `"group"` - The aggregated vector stores usage details of the specific time bucket. + - `"tenant_group"` - - `object: "organization.usage.vector_stores.result"` + - `object: "project.group"` - - `"organization.usage.vector_stores.result"` + Always `project.group`. - - `usage_bytes: number` + - `"project.group"` - The vector stores usage in bytes. + - `project_id: string` - - `project_id: optional string` + Identifier of the project. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +# Roles - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +## Assign project role to group - The aggregated code interpreter sessions usage details of the specific time bucket. +**post** `/projects/{project_id}/groups/{group_id}/roles` - - `num_sessions: number` +Assigns a project role to a group within a project. - The number of code interpreter sessions. +### Path Parameters - - `object: "organization.usage.code_interpreter_sessions.result"` +- `project_id: string` - - `"organization.usage.code_interpreter_sessions.result"` +- `group_id: string` - - `project_id: optional string` +### Body Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `role_id: string` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + Identifier of the role to assign. - The aggregated file search calls usage details of the specific time bucket. +### Returns - - `num_requests: number` +- `group: object { id, created_at, name, 2 more }` - The count of file search calls. + Summary information about a group returned in role assignment responses. - - `object: "organization.usage.file_searches.result"` + - `id: string` - - `"organization.usage.file_searches.result"` + Identifier for the group. - - `api_key_id: optional string` + - `created_at: number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Unix timestamp (in seconds) when the group was created. - - `project_id: optional string` + - `name: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Display name of the group. - - `user_id: optional string` + - `object: "group"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Always `group`. - - `vector_store_id: optional string` + - `"group"` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `scim_managed: boolean` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + Whether the group is managed through SCIM. - The aggregated web search calls usage details of the specific time bucket. +- `object: "group.role"` - - `num_model_requests: number` + Always `group.role`. - The count of model requests. + - `"group.role"` - - `num_requests: number` +- `role: Role` - The count of web search calls. + Details about a role that can be assigned through the public Roles API. - - `object: "organization.usage.web_searches.result"` + - `id: string` - - `"organization.usage.web_searches.result"` + Identifier for the role. - - `api_key_id: optional string` + - `description: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Optional description of the role. - - `context_level: optional string` + - `name: string` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + Unique name for the role. - - `model: optional string` + - `object: "role"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Always `role`. - - `project_id: optional string` + - `"role"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `permissions: array of string` - - `user_id: optional string` + Permissions granted by the role. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `predefined_role: boolean` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + Whether the role is predefined and managed by OpenAI. - The aggregated costs details of the specific time bucket. + - `resource_type: string` - - `object: "organization.costs.result"` + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `"organization.costs.result"` +### Example - - `amount: optional object { currency, value }` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "role_id": "role_id" + }' +``` - The monetary value in its associated currency. +#### Response - - `currency: optional string` +```json +{ + "group": { + "id": "id", + "created_at": 0, + "name": "name", + "object": "group", + "scim_managed": true + }, + "object": "group.role", + "role": { + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" + } +} +``` - Lowercase ISO-4217 currency e.g. "usd" +### Example - - `value: optional number` +```http +curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8PROJ" + }' +``` - The numeric value of the cost. +#### Response - - `api_key_id: optional string` +```json +{ + "object": "group.role", + "group": { + "object": "group", + "id": "group_01J1F8ABCDXYZ", + "name": "Support Team", + "created_at": 1711471533, + "scim_managed": false + }, + "role": { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } +} +``` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +## Unassign project role from group - - `line_item: optional string` +**delete** `/projects/{project_id}/groups/{group_id}/roles/{role_id}` - When `group_by=line_item`, this field provides the line item of the grouped costs result. +Unassigns a project role from a group within a project. - - `project_id: optional string` +### Path Parameters - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +- `project_id: string` - - `quantity: optional number` +- `group_id: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +- `role_id: string` - - `start_time: number` +### Returns -- `has_more: boolean` +- `deleted: boolean` -- `next_page: string` + Whether the assignment was removed. -- `object: "page"` +- `object: string` - - `"page"` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. ### Example ```http -curl https://api.openai.com/v1/organization/usage/file_search_calls \ +curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles/$ROLE_ID \ + -X DELETE \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -8915,576 +9797,615 @@ curl https://api.openai.com/v1/organization/usage/file_search_calls \ ```json { - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 - } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" + "deleted": true, + "object": "object" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/file_search_calls?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.file_searches.result", - "num_requests": 2, - "project_id": null, - "user_id": null, - "api_key_id": null, - "vector_store_id": null - } - ] - } - ], - "has_more": false, - "next_page": null + "object": "group.role.deleted", + "deleted": true } ``` -## Web search calls - -**get** `/organization/usage/web_search_calls` - -Get web search calls usage details for the organization. - -### Query Parameters - -- `start_time: number` - - Start time (Unix seconds) of the query time range, inclusive. - -- `api_key_ids: optional array of string` - - Return only usage for these API keys. - -- `bucket_width: optional "1m" or "1h" or "1d"` - - Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - - `"1m"` - - - `"1h"` - - - `"1d"` - -- `context_levels: optional array of "low" or "medium" or "high"` +## List project group role assignments - Return only web search usage for these context levels. +**get** `/projects/{project_id}/groups/{group_id}/roles` - - `"low"` +Lists the project roles assigned to a group within a project. - - `"medium"` +### Path Parameters - - `"high"` +- `project_id: string` -- `end_time: optional number` +- `group_id: string` - End time (Unix seconds) of the query time range, exclusive. +### Query Parameters -- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 2 more` +- `after: optional string` - Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `context_level` or any combination of them. + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles. - - `"project_id"` +- `limit: optional number` - - `"user_id"` + A limit on the number of project role assignments to return. - - `"api_key_id"` +- `order: optional "asc" or "desc"` - - `"model"` + Sort order for the returned project roles. - - `"context_level"` + - `"asc"` -- `limit: optional number` + - `"desc"` - Specifies the number of buckets to return. +### Returns - - `bucket_width=1d`: default: 7, max: 31 - - `bucket_width=1h`: default: 24, max: 168 - - `bucket_width=1m`: default: 60, max: 1440 +- `data: array of object { id, assignment_sources, created_at, 9 more }` -- `models: optional array of string` + Role assignments returned in the current page. - Return only usage for these models. + - `id: string` -- `page: optional string` + Identifier for the role. - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + - `assignment_sources: array of object { principal_id, principal_type }` -- `project_ids: optional array of string` + Principals from which the role assignment is inherited, when available. - Return only usage for these projects. + - `principal_id: string` -- `user_ids: optional array of string` + - `principal_type: string` - Return only usage for these users. + - `created_at: number` -### Returns + When the role was created. -- `data: array of object { end_time, object, results, start_time }` + - `created_by: string` - - `end_time: number` + Identifier of the actor who created the role. - - `object: "bucket"` + - `created_by_user_obj: map[unknown]` - - `"bucket"` + User details for the actor that created the role, when available. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `description: string` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + Description of the role. - The aggregated completions usage details of the specific time bucket. + - `metadata: map[unknown]` - - `input_tokens: number` + Arbitrary metadata stored on the role. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `name: string` - - `num_model_requests: number` + Name of the role. - The count of requests made to the model. + - `permissions: array of string` - - `object: "organization.usage.completions.result"` + Permissions associated with the role. - - `"organization.usage.completions.result"` + - `predefined_role: boolean` - - `output_tokens: number` + Whether the role is predefined by OpenAI. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `resource_type: string` - - `api_key_id: optional string` + Resource type the role applies to. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `updated_at: number` - - `batch: optional boolean` + When the role was last updated. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +- `has_more: boolean` - - `input_audio_tokens: optional number` + Whether additional assignments are available when paginating. - The aggregated number of uncached audio input tokens used. +- `next: string` - - `input_cache_write_tokens: optional number` + Cursor to fetch the next page of results, or `null` when there are no more assignments. - The aggregated number of input tokens written to the cache. +- `object: "list"` - - `input_cached_audio_tokens: optional number` + Always `list`. - The aggregated number of cached audio input tokens used. + - `"list"` - - `input_cached_image_tokens: optional number` +### Example - The aggregated number of cached image input tokens used. +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `input_cached_text_tokens: optional number` +#### Response - The aggregated number of cached text input tokens used. +```json +{ + "data": [ + { + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `input_cached_tokens: optional number` +### Example - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```http +curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `input_image_tokens: optional number` +#### Response - The aggregated number of uncached image input tokens used. +```json +{ + "object": "list", + "data": [ + { + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null +} +``` - - `input_text_tokens: optional number` +## Retrieve project group role - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +**get** `/projects/{project_id}/groups/{group_id}/roles/{role_id}` - - `input_uncached_tokens: optional number` +Retrieves a project role assigned to a group. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +### Path Parameters - - `model: optional string` +- `project_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. +- `group_id: string` - - `output_audio_tokens: optional number` +- `role_id: string` - The aggregated number of audio output tokens used. +### Returns - - `output_image_tokens: optional number` +- `id: string` - The aggregated number of image output tokens used. + Identifier for the role. - - `output_text_tokens: optional number` +- `assignment_sources: array of object { principal_id, principal_type }` - The aggregated number of text output tokens used. + Principals from which the role assignment is inherited, when available. - - `project_id: optional string` + - `principal_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `principal_type: string` - - `service_tier: optional string` +- `created_at: number` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + When the role was created. - - `user_id: optional string` +- `created_by: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Identifier of the actor who created the role. - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +- `created_by_user_obj: map[unknown]` - The aggregated embeddings usage details of the specific time bucket. + User details for the actor that created the role, when available. - - `input_tokens: number` +- `description: string` - The aggregated number of input tokens used. + Description of the role. - - `num_model_requests: number` +- `metadata: map[unknown]` - The count of requests made to the model. + Arbitrary metadata stored on the role. - - `object: "organization.usage.embeddings.result"` +- `name: string` - - `"organization.usage.embeddings.result"` + Name of the role. - - `api_key_id: optional string` +- `permissions: array of string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Permissions associated with the role. - - `model: optional string` +- `predefined_role: boolean` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the role is predefined by OpenAI. - - `project_id: optional string` +- `resource_type: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Resource type the role applies to. - - `user_id: optional string` +- `updated_at: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + When the role was last updated. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +### Example - The aggregated moderations usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles/$ROLE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `input_tokens: number` +#### Response - The aggregated number of input tokens used. +```json +{ + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 +} +``` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.moderations.result"` +#### Response - - `"organization.usage.moderations.result"` +```json +{ + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": null, + "metadata": {}, + "assignment_sources": null +} +``` - - `api_key_id: optional string` +## Domain Types - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Role Create Response - - `model: optional string` +- `RoleCreateResponse object { group, object, role }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Role assignment linking a group to a role. - - `project_id: optional string` + - `group: object { id, created_at, name, 2 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Summary information about a group returned in role assignment responses. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Identifier for the group. - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + - `created_at: number` - The aggregated images usage details of the specific time bucket. + Unix timestamp (in seconds) when the group was created. - - `images: number` + - `name: string` - The number of images processed. + Display name of the group. - - `num_model_requests: number` + - `object: "group"` - The count of requests made to the model. + Always `group`. - - `object: "organization.usage.images.result"` + - `"group"` - - `"organization.usage.images.result"` + - `scim_managed: boolean` - - `api_key_id: optional string` + Whether the group is managed through SCIM. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `object: "group.role"` - - `model: optional string` + Always `group.role`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"group.role"` - - `project_id: optional string` + - `role: Role` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Details about a role that can be assigned through the public Roles API. - - `size: optional string` + - `id: string` - When `group_by=size`, this field provides the image size of the grouped usage result. + Identifier for the role. - - `source: optional string` + - `description: string` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + Optional description of the role. - - `user_id: optional string` + - `name: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Unique name for the role. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `object: "role"` - The aggregated audio speeches usage details of the specific time bucket. + Always `role`. - - `characters: number` + - `"role"` - The number of characters processed. + - `permissions: array of string` - - `num_model_requests: number` + Permissions granted by the role. - The count of requests made to the model. + - `predefined_role: boolean` - - `object: "organization.usage.audio_speeches.result"` + Whether the role is predefined and managed by OpenAI. - - `"organization.usage.audio_speeches.result"` + - `resource_type: string` - - `api_key_id: optional string` + Resource type the role is bound to (for example `api.organization` or `api.project`). - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Role Delete Response - - `model: optional string` +- `RoleDeleteResponse object { deleted, object }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Confirmation payload returned after unassigning a role. - - `project_id: optional string` + - `deleted: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether the assignment was removed. - - `user_id: optional string` + - `object: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +### Role List Response - The aggregated audio transcriptions usage details of the specific time bucket. +- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` - - `num_model_requests: number` + Detailed information about a role assignment entry returned when listing assignments. - The count of requests made to the model. + - `id: string` - - `object: "organization.usage.audio_transcriptions.result"` + Identifier for the role. - - `"organization.usage.audio_transcriptions.result"` + - `assignment_sources: array of object { principal_id, principal_type }` - - `seconds: number` + Principals from which the role assignment is inherited, when available. - The number of seconds processed. + - `principal_id: string` - - `api_key_id: optional string` + - `principal_type: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `created_at: number` - - `model: optional string` + When the role was created. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `created_by: string` - - `project_id: optional string` + Identifier of the actor who created the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `created_by_user_obj: map[unknown]` - - `user_id: optional string` + User details for the actor that created the role, when available. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `description: string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + Description of the role. - The aggregated vector stores usage details of the specific time bucket. + - `metadata: map[unknown]` - - `object: "organization.usage.vector_stores.result"` + Arbitrary metadata stored on the role. - - `"organization.usage.vector_stores.result"` + - `name: string` - - `usage_bytes: number` + Name of the role. - The vector stores usage in bytes. + - `permissions: array of string` - - `project_id: optional string` + Permissions associated with the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `predefined_role: boolean` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + Whether the role is predefined by OpenAI. - The aggregated code interpreter sessions usage details of the specific time bucket. + - `resource_type: string` - - `num_sessions: number` + Resource type the role applies to. - The number of code interpreter sessions. + - `updated_at: number` - - `object: "organization.usage.code_interpreter_sessions.result"` + When the role was last updated. - - `"organization.usage.code_interpreter_sessions.result"` +### Role Retrieve Response - - `project_id: optional string` +- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Detailed information about a role assignment entry returned when listing assignments. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `id: string` - The aggregated file search calls usage details of the specific time bucket. + Identifier for the role. - - `num_requests: number` + - `assignment_sources: array of object { principal_id, principal_type }` - The count of file search calls. + Principals from which the role assignment is inherited, when available. - - `object: "organization.usage.file_searches.result"` + - `principal_id: string` - - `"organization.usage.file_searches.result"` + - `principal_type: string` - - `api_key_id: optional string` + - `created_at: number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + When the role was created. - - `project_id: optional string` + - `created_by: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Identifier of the actor who created the role. - - `user_id: optional string` + - `created_by_user_obj: map[unknown]` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + User details for the actor that created the role, when available. - - `vector_store_id: optional string` + - `description: string` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + Description of the role. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `metadata: map[unknown]` - The aggregated web search calls usage details of the specific time bucket. + Arbitrary metadata stored on the role. - - `num_model_requests: number` + - `name: string` - The count of model requests. + Name of the role. - - `num_requests: number` + - `permissions: array of string` - The count of web search calls. + Permissions associated with the role. - - `object: "organization.usage.web_searches.result"` + - `predefined_role: boolean` - - `"organization.usage.web_searches.result"` + Whether the role is predefined by OpenAI. - - `api_key_id: optional string` + - `resource_type: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Resource type the role applies to. - - `context_level: optional string` + - `updated_at: number` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + When the role was last updated. - - `model: optional string` +# Hosted Tool Permissions - When `group_by=model`, this field provides the model name of the grouped usage result. +## Retrieve project hosted tool permissions - - `project_id: optional string` +**get** `/organization/projects/{project_id}/hosted_tool_permissions` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Returns hosted tool permissions for a project. - - `user_id: optional string` +### Path Parameters - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `project_id: string` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +### Returns - The aggregated costs details of the specific time bucket. +- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` - - `object: "organization.costs.result"` + Represents hosted tool permissions for a project. - - `"organization.costs.result"` + - `code_interpreter: object { enabled }` - - `amount: optional object { currency, value }` + Permission state for a single hosted tool on a project. - The monetary value in its associated currency. + - `enabled: boolean` - - `currency: optional string` + Whether the hosted tool is enabled for the project. - Lowercase ISO-4217 currency e.g. "usd" + - `file_search: object { enabled }` - - `value: optional number` + Permission state for a single hosted tool on a project. - The numeric value of the cost. + - `enabled: boolean` - - `api_key_id: optional string` + Whether the hosted tool is enabled for the project. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `image_generation: object { enabled }` - - `line_item: optional string` + Permission state for a single hosted tool on a project. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `enabled: boolean` - - `project_id: optional string` + Whether the hosted tool is enabled for the project. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `mcp: object { enabled }` - - `quantity: optional number` + Permission state for a single hosted tool on a project. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `enabled: boolean` - - `start_time: number` + Whether the hosted tool is enabled for the project. -- `has_more: boolean` + - `web_search: object { enabled }` -- `next_page: string` + Permission state for a single hosted tool on a project. -- `object: "page"` + - `enabled: boolean` - - `"page"` + Whether the hosted tool is enabled for the project. ### Example ```http -curl https://api.openai.com/v1/organization/usage/web_search_calls \ +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/hosted_tool_permissions \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -9492,548 +10413,629 @@ curl https://api.openai.com/v1/organization/usage/web_search_calls \ ```json { - "data": [ - { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, - "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 + "code_interpreter": { + "enabled": true + }, + "file_search": { + "enabled": true + }, + "image_generation": { + "enabled": true + }, + "mcp": { + "enabled": true + }, + "web_search": { + "enabled": true } - ], - "has_more": true, - "next_page": "next_page", - "object": "page" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/usage/web_search_calls?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", - "data": [ - { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.usage.web_searches.result", - "num_model_requests": 2, - "num_requests": 2, - "project_id": null, - "user_id": null, - "api_key_id": null, - "model": null, - "context_level": null - } - ] + "file_search": { + "enabled": true + }, + "web_search": { + "enabled": true + }, + "image_generation": { + "enabled": true + }, + "mcp": { + "enabled": true + }, + "code_interpreter": { + "enabled": true } - ], - "has_more": false, - "next_page": null } ``` -## Costs - -**get** `/organization/costs` - -Get costs details for the organization. - -### Query Parameters - -- `start_time: number` - - Start time (Unix seconds) of the query time range, inclusive. - -- `api_key_ids: optional array of string` - - Return only costs for these API keys. - -- `bucket_width: optional "1d"` - - Width of each time bucket in response. Currently only `1d` is supported, default to `1d`. - - - `"1d"` - -- `end_time: optional number` - - End time (Unix seconds) of the query time range, exclusive. +## Modify project hosted tool permissions -- `group_by: optional array of "project_id" or "line_item" or "api_key_id"` +**post** `/organization/projects/{project_id}/hosted_tool_permissions` - Group the costs by the specified fields. Support fields include `project_id`, `line_item`, `api_key_id` and any combination of them. +Updates hosted tool permissions for a project. - - `"project_id"` +### Path Parameters - - `"line_item"` +- `project_id: string` - - `"api_key_id"` +### Body Parameters -- `limit: optional number` +- `code_interpreter: optional object { enabled }` - A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7. + The code interpreter permission update. -- `page: optional string` + - `enabled: boolean` - A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. + Whether to enable the hosted tool for the project. -- `project_ids: optional array of string` +- `file_search: optional object { enabled }` - Return only costs for these projects. + The file search permission update. -### Returns + - `enabled: boolean` -- `data: array of object { end_time, object, results, start_time }` + Whether to enable the hosted tool for the project. - - `end_time: number` +- `image_generation: optional object { enabled }` - - `object: "bucket"` + The image generation permission update. - - `"bucket"` + - `enabled: boolean` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + Whether to enable the hosted tool for the project. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +- `mcp: optional object { enabled }` - The aggregated completions usage details of the specific time bucket. + The MCP permission update. - - `input_tokens: number` + - `enabled: boolean` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Whether to enable the hosted tool for the project. - - `num_model_requests: number` +- `web_search: optional object { enabled }` - The count of requests made to the model. + The web search permission update. - - `object: "organization.usage.completions.result"` + - `enabled: boolean` - - `"organization.usage.completions.result"` + Whether to enable the hosted tool for the project. - - `output_tokens: number` +### Returns - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` - - `api_key_id: optional string` + Represents hosted tool permissions for a project. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `code_interpreter: object { enabled }` - - `batch: optional boolean` + Permission state for a single hosted tool on a project. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `enabled: boolean` - - `input_audio_tokens: optional number` + Whether the hosted tool is enabled for the project. - The aggregated number of uncached audio input tokens used. + - `file_search: object { enabled }` - - `input_cache_write_tokens: optional number` + Permission state for a single hosted tool on a project. - The aggregated number of input tokens written to the cache. + - `enabled: boolean` - - `input_cached_audio_tokens: optional number` + Whether the hosted tool is enabled for the project. - The aggregated number of cached audio input tokens used. + - `image_generation: object { enabled }` - - `input_cached_image_tokens: optional number` + Permission state for a single hosted tool on a project. - The aggregated number of cached image input tokens used. + - `enabled: boolean` - - `input_cached_text_tokens: optional number` + Whether the hosted tool is enabled for the project. - The aggregated number of cached text input tokens used. + - `mcp: object { enabled }` - - `input_cached_tokens: optional number` + Permission state for a single hosted tool on a project. - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `enabled: boolean` - - `input_image_tokens: optional number` + Whether the hosted tool is enabled for the project. - The aggregated number of uncached image input tokens used. + - `web_search: object { enabled }` - - `input_text_tokens: optional number` + Permission state for a single hosted tool on a project. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `enabled: boolean` - - `input_uncached_tokens: optional number` + Whether the hosted tool is enabled for the project. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +### Example - - `model: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/hosted_tool_permissions \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `output_audio_tokens: optional number` +```json +{ + "code_interpreter": { + "enabled": true + }, + "file_search": { + "enabled": true + }, + "image_generation": { + "enabled": true + }, + "mcp": { + "enabled": true + }, + "web_search": { + "enabled": true + } +} +``` - The aggregated number of audio output tokens used. +### Example - - `output_image_tokens: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "file_search": { + "enabled": true + }, + "image_generation": { + "enabled": false + } + }' +``` - The aggregated number of image output tokens used. +#### Response - - `output_text_tokens: optional number` +```json +{ + "file_search": { + "enabled": true + }, + "web_search": { + "enabled": true + }, + "image_generation": { + "enabled": false + }, + "mcp": { + "enabled": true + }, + "code_interpreter": { + "enabled": true + } +} +``` - The aggregated number of text output tokens used. +## Domain Types - - `project_id: optional string` +### Project Hosted Tool Permissions - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` - - `service_tier: optional string` + Represents hosted tool permissions for a project. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `code_interpreter: object { enabled }` - - `user_id: optional string` + Permission state for a single hosted tool on a project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `enabled: boolean` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + Whether the hosted tool is enabled for the project. - The aggregated embeddings usage details of the specific time bucket. + - `file_search: object { enabled }` - - `input_tokens: number` + Permission state for a single hosted tool on a project. - The aggregated number of input tokens used. + - `enabled: boolean` - - `num_model_requests: number` + Whether the hosted tool is enabled for the project. - The count of requests made to the model. + - `image_generation: object { enabled }` - - `object: "organization.usage.embeddings.result"` + Permission state for a single hosted tool on a project. - - `"organization.usage.embeddings.result"` + - `enabled: boolean` - - `api_key_id: optional string` + Whether the hosted tool is enabled for the project. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `mcp: object { enabled }` - - `model: optional string` + Permission state for a single hosted tool on a project. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `enabled: boolean` - - `project_id: optional string` + Whether the hosted tool is enabled for the project. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `web_search: object { enabled }` - - `user_id: optional string` + Permission state for a single hosted tool on a project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `enabled: boolean` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + Whether the hosted tool is enabled for the project. - The aggregated moderations usage details of the specific time bucket. +# Model Permissions - - `input_tokens: number` +## Delete project model permissions - The aggregated number of input tokens used. +**delete** `/organization/projects/{project_id}/model_permissions` - - `num_model_requests: number` +Deletes model permissions for a project. - The count of requests made to the model. +### Path Parameters - - `object: "organization.usage.moderations.result"` +- `project_id: string` - - `"organization.usage.moderations.result"` +### Returns - - `api_key_id: optional string` +- `ProjectModelPermissionsDeleted object { deleted, object }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Confirmation payload returned after deleting project model permissions. - - `model: optional string` + - `deleted: boolean` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the project model permissions were deleted. - - `project_id: optional string` + - `object: "project.model_permissions.deleted"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The object type, which is always `project.model_permissions.deleted`. - - `user_id: optional string` + - `"project.model_permissions.deleted"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated images usage details of the specific time bucket. +#### Response - - `images: number` +```json +{ + "deleted": true, + "object": "project.model_permissions.deleted" +} +``` - The number of images processed. +### Example - - `num_model_requests: number` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The count of requests made to the model. +#### Response - - `object: "organization.usage.images.result"` +```json +{ + "object": "project.model_permissions.deleted", + "deleted": true +} +``` - - `"organization.usage.images.result"` +## Retrieve project model permissions - - `api_key_id: optional string` +**get** `/organization/projects/{project_id}/model_permissions` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +Returns model permissions for a project. - - `model: optional string` +### Path Parameters - When `group_by=model`, this field provides the model name of the grouped usage result. +- `project_id: string` - - `project_id: optional string` +### Returns - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `ProjectModelPermissions object { mode, model_ids, object }` - - `size: optional string` + Represents the model allowlist or denylist policy for a project. - When `group_by=size`, this field provides the image size of the grouped usage result. + - `mode: "allow_list" or "deny_list"` - - `source: optional string` + Whether the project uses an allowlist or a denylist. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `"allow_list"` - - `user_id: optional string` + - `"deny_list"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `model_ids: array of string` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + The model IDs included in the model permissions policy. - The aggregated audio speeches usage details of the specific time bucket. + - `object: "project.model_permissions"` - - `characters: number` + The object type, which is always `project.model_permissions`. - The number of characters processed. + - `"project.model_permissions"` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `object: "organization.usage.audio_speeches.result"` +#### Response - - `"organization.usage.audio_speeches.result"` +```json +{ + "mode": "allow_list", + "model_ids": [ + "string" + ], + "object": "project.model_permissions" +} +``` - - `api_key_id: optional string` +### Example - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `model: optional string` +#### Response - When `group_by=model`, this field provides the model name of the grouped usage result. +```json +{ + "object": "project.model_permissions", + "mode": "allow_list", + "model_ids": [ + "gpt-4.1", + "o3" + ] +} +``` - - `project_id: optional string` +## Modify project model permissions - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**post** `/organization/projects/{project_id}/model_permissions` - - `user_id: optional string` +Updates model permissions for a project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Path Parameters - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +- `project_id: string` - The aggregated audio transcriptions usage details of the specific time bucket. +### Body Parameters - - `num_model_requests: number` +- `mode: "allow_list" or "deny_list"` - The count of requests made to the model. + The model permissions mode to apply. - - `object: "organization.usage.audio_transcriptions.result"` + - `"allow_list"` - - `"organization.usage.audio_transcriptions.result"` + - `"deny_list"` - - `seconds: number` +- `model_ids: array of string` - The number of seconds processed. + The model IDs included in this permissions policy. - - `api_key_id: optional string` +### Returns - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `ProjectModelPermissions object { mode, model_ids, object }` - - `model: optional string` + Represents the model allowlist or denylist policy for a project. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `mode: "allow_list" or "deny_list"` - - `project_id: optional string` + Whether the project uses an allowlist or a denylist. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"allow_list"` - - `user_id: optional string` + - `"deny_list"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `model_ids: array of string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + The model IDs included in the model permissions policy. - The aggregated vector stores usage details of the specific time bucket. + - `object: "project.model_permissions"` - - `object: "organization.usage.vector_stores.result"` + The object type, which is always `project.model_permissions`. - - `"organization.usage.vector_stores.result"` + - `"project.model_permissions"` - - `usage_bytes: number` +### Example - The vector stores usage in bytes. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "mode": "allow_list", + "model_ids": [ + "string" + ] + }' +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```json +{ + "mode": "allow_list", + "model_ids": [ + "string" + ], + "object": "project.model_permissions" +} +``` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +### Example - The aggregated code interpreter sessions usage details of the specific time bucket. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "mode": "deny_list", + "model_ids": [ + "o3" + ] + }' +``` - - `num_sessions: number` +#### Response - The number of code interpreter sessions. +```json +{ + "object": "project.model_permissions", + "mode": "deny_list", + "model_ids": [ + "o3" + ] +} +``` - - `object: "organization.usage.code_interpreter_sessions.result"` +## Domain Types - - `"organization.usage.code_interpreter_sessions.result"` +### Project Model Permissions - - `project_id: optional string` +- `ProjectModelPermissions object { mode, model_ids, object }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Represents the model allowlist or denylist policy for a project. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `mode: "allow_list" or "deny_list"` - The aggregated file search calls usage details of the specific time bucket. + Whether the project uses an allowlist or a denylist. - - `num_requests: number` + - `"allow_list"` - The count of file search calls. + - `"deny_list"` - - `object: "organization.usage.file_searches.result"` + - `model_ids: array of string` - - `"organization.usage.file_searches.result"` + The model IDs included in the model permissions policy. - - `api_key_id: optional string` + - `object: "project.model_permissions"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The object type, which is always `project.model_permissions`. - - `project_id: optional string` + - `"project.model_permissions"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Project Model Permissions Deleted - - `user_id: optional string` +- `ProjectModelPermissionsDeleted object { deleted, object }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Confirmation payload returned after deleting project model permissions. - - `vector_store_id: optional string` + - `deleted: boolean` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + Whether the project model permissions were deleted. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `object: "project.model_permissions.deleted"` - The aggregated web search calls usage details of the specific time bucket. + The object type, which is always `project.model_permissions.deleted`. - - `num_model_requests: number` + - `"project.model_permissions.deleted"` - The count of model requests. +# Rate Limits - - `num_requests: number` +## List project rate limits - The count of web search calls. +**get** `/organization/projects/{project_id}/rate_limits` - - `object: "organization.usage.web_searches.result"` +Returns the rate limits per model for a project. - - `"organization.usage.web_searches.result"` +### Path Parameters - - `api_key_id: optional string` +- `project_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Query Parameters - - `context_level: optional string` +- `after: optional string` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `model: optional string` +- `before: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, beginning with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `project_id: optional string` +- `limit: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + A limit on the number of objects to be returned. The default is 100. - - `user_id: optional string` +### Returns - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `data: array of ProjectRateLimit` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `id: string` - The aggregated costs details of the specific time bucket. + The identifier, which can be referenced in API endpoints. - - `object: "organization.costs.result"` + - `max_requests_per_1_minute: number` - - `"organization.costs.result"` + The maximum requests per minute. - - `amount: optional object { currency, value }` + - `max_tokens_per_1_minute: number` - The monetary value in its associated currency. + The maximum tokens per minute. - - `currency: optional string` + - `model: string` - Lowercase ISO-4217 currency e.g. "usd" + The model this rate limit applies to. - - `value: optional number` + - `object: "project.rate_limit"` - The numeric value of the cost. + The object type, which is always `project.rate_limit` - - `api_key_id: optional string` + - `"project.rate_limit"` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `batch_1_day_max_input_tokens: optional number` - - `line_item: optional string` + The maximum batch input tokens per day. Only present for relevant models. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `max_audio_megabytes_per_1_minute: optional number` - - `project_id: optional string` + The maximum audio megabytes per minute. Only present for relevant models. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `max_images_per_1_minute: optional number` - - `quantity: optional number` + The maximum images per minute. Only present for relevant models. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `max_requests_per_1_day: optional number` - - `start_time: number` + The maximum requests per day. Only present for relevant models. - `has_more: boolean` -- `next_page: string` +- `object: "list"` -- `object: "page"` + - `"list"` - - `"page"` +- `first_id: optional string` + +- `last_id: optional string` ### Example ```http -curl https://api.openai.com/v1/organization/costs \ +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/rate_limits \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -10043,4248 +11045,5838 @@ curl https://api.openai.com/v1/organization/costs \ { "data": [ { - "end_time": 0, - "object": "bucket", - "results": [ - { - "input_tokens": 0, - "num_model_requests": 0, - "object": "organization.usage.completions.result", - "output_tokens": 0, - "api_key_id": "api_key_id", - "batch": true, - "input_audio_tokens": 0, - "input_cache_write_tokens": 0, - "input_cached_audio_tokens": 0, - "input_cached_image_tokens": 0, - "input_cached_text_tokens": 0, - "input_cached_tokens": 0, - "input_image_tokens": 0, - "input_text_tokens": 0, - "input_uncached_tokens": 0, + "id": "id", + "max_requests_per_1_minute": 0, + "max_tokens_per_1_minute": 0, "model": "model", - "output_audio_tokens": 0, - "output_image_tokens": 0, - "output_text_tokens": 0, - "project_id": "project_id", - "service_tier": "service_tier", - "user_id": "user_id" - } - ], - "start_time": 0 + "object": "project.rate_limit", + "batch_1_day_max_input_tokens": 0, + "max_audio_megabytes_per_1_minute": 0, + "max_images_per_1_minute": 0, + "max_requests_per_1_day": 0 } ], "has_more": true, - "next_page": "next_page", - "object": "page" + "object": "list", + "first_id": "first_id", + "last_id": "last_id" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" +curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "page", + "object": "list", "data": [ { - "object": "bucket", - "start_time": 1730419200, - "end_time": 1730505600, - "results": [ - { - "object": "organization.costs.result", - "amount": { - "value": 0.06, - "currency": "usd" - }, - "line_item": null, - "project_id": null, - "api_key_id": null, - "quantity": null - } - ] + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 } ], - "has_more": false, - "next_page": null + "first_id": "rl-ada", + "last_id": "rl-ada", + "has_more": false } ``` -## Domain Types +## Modify project rate limit -### Usage Audio Speeches Response +**post** `/organization/projects/{project_id}/rate_limits/{rate_limit_id}` -- `UsageAudioSpeechesResponse object { data, has_more, next_page, object }` +Updates a project rate limit. - - `data: array of object { end_time, object, results, start_time }` +### Path Parameters + +- `project_id: string` + +- `rate_limit_id: string` + +### Body Parameters + +- `batch_1_day_max_input_tokens: optional number` + + The maximum batch input tokens per day. Only relevant for certain models. + +- `max_audio_megabytes_per_1_minute: optional number` + + The maximum audio megabytes per minute. Only relevant for certain models. + +- `max_images_per_1_minute: optional number` + + The maximum images per minute. Only relevant for certain models. + +- `max_requests_per_1_day: optional number` + + The maximum requests per day. Only relevant for certain models. + +- `max_requests_per_1_minute: optional number` + + The maximum requests per minute. + +- `max_tokens_per_1_minute: optional number` + + The maximum tokens per minute. + +### Returns + +- `ProjectRateLimit object { id, max_requests_per_1_minute, max_tokens_per_1_minute, 6 more }` + + Represents a project rate limit config. + + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `max_requests_per_1_minute: number` + + The maximum requests per minute. - - `end_time: number` + - `max_tokens_per_1_minute: number` - - `object: "bucket"` + The maximum tokens per minute. - - `"bucket"` + - `model: string` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + The model this rate limit applies to. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `object: "project.rate_limit"` - The aggregated completions usage details of the specific time bucket. + The object type, which is always `project.rate_limit` - - `input_tokens: number` + - `"project.rate_limit"` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `batch_1_day_max_input_tokens: optional number` - - `num_model_requests: number` + The maximum batch input tokens per day. Only present for relevant models. - The count of requests made to the model. + - `max_audio_megabytes_per_1_minute: optional number` - - `object: "organization.usage.completions.result"` + The maximum audio megabytes per minute. Only present for relevant models. - - `"organization.usage.completions.result"` + - `max_images_per_1_minute: optional number` - - `output_tokens: number` + The maximum images per minute. Only present for relevant models. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `max_requests_per_1_day: optional number` - - `api_key_id: optional string` + The maximum requests per day. Only present for relevant models. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `batch: optional boolean` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/rate_limits/$RATE_LIMIT_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +#### Response - - `input_audio_tokens: optional number` +```json +{ + "id": "id", + "max_requests_per_1_minute": 0, + "max_tokens_per_1_minute": 0, + "model": "model", + "object": "project.rate_limit", + "batch_1_day_max_input_tokens": 0, + "max_audio_megabytes_per_1_minute": 0, + "max_images_per_1_minute": 0, + "max_requests_per_1_day": 0 +} +``` - The aggregated number of uncached audio input tokens used. +### Example - - `input_cache_write_tokens: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "max_requests_per_1_minute": 500 + }' +``` - The aggregated number of input tokens written to the cache. +#### Response - - `input_cached_audio_tokens: optional number` +```json +{ + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } +``` - The aggregated number of cached audio input tokens used. +## Domain Types - - `input_cached_image_tokens: optional number` +### Project Rate Limit - The aggregated number of cached image input tokens used. +- `ProjectRateLimit object { id, max_requests_per_1_minute, max_tokens_per_1_minute, 6 more }` - - `input_cached_text_tokens: optional number` + Represents a project rate limit config. - The aggregated number of cached text input tokens used. + - `id: string` - - `input_cached_tokens: optional number` + The identifier, which can be referenced in API endpoints. - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `max_requests_per_1_minute: number` - - `input_image_tokens: optional number` + The maximum requests per minute. - The aggregated number of uncached image input tokens used. + - `max_tokens_per_1_minute: number` - - `input_text_tokens: optional number` + The maximum tokens per minute. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `model: string` - - `input_uncached_tokens: optional number` + The model this rate limit applies to. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + - `object: "project.rate_limit"` - - `model: optional string` + The object type, which is always `project.rate_limit` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"project.rate_limit"` - - `output_audio_tokens: optional number` + - `batch_1_day_max_input_tokens: optional number` - The aggregated number of audio output tokens used. + The maximum batch input tokens per day. Only present for relevant models. - - `output_image_tokens: optional number` + - `max_audio_megabytes_per_1_minute: optional number` - The aggregated number of image output tokens used. + The maximum audio megabytes per minute. Only present for relevant models. - - `output_text_tokens: optional number` + - `max_images_per_1_minute: optional number` - The aggregated number of text output tokens used. + The maximum images per minute. Only present for relevant models. - - `project_id: optional string` + - `max_requests_per_1_day: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The maximum requests per day. Only present for relevant models. - - `service_tier: optional string` +# Roles - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +## Create project role - - `user_id: optional string` +**post** `/projects/{project_id}/roles` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Creates a custom role for a project. - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +### Path Parameters - The aggregated embeddings usage details of the specific time bucket. +- `project_id: string` - - `input_tokens: number` +### Body Parameters - The aggregated number of input tokens used. +- `permissions: array of string` - - `num_model_requests: number` + Permissions to grant to the role. - The count of requests made to the model. +- `role_name: string` - - `object: "organization.usage.embeddings.result"` + Unique name for the role. - - `"organization.usage.embeddings.result"` +- `description: optional string` - - `api_key_id: optional string` + Optional description of the role. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Returns - - `model: optional string` +- `Role object { id, description, name, 4 more }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Details about a role that can be assigned through the public Roles API. - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Identifier for the role. - - `user_id: optional string` + - `description: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Optional description of the role. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `name: string` - The aggregated moderations usage details of the specific time bucket. + Unique name for the role. - - `input_tokens: number` + - `object: "role"` - The aggregated number of input tokens used. + Always `role`. - - `num_model_requests: number` + - `"role"` - The count of requests made to the model. + - `permissions: array of string` - - `object: "organization.usage.moderations.result"` + Permissions granted by the role. - - `"organization.usage.moderations.result"` + - `predefined_role: boolean` - - `api_key_id: optional string` + Whether the role is predefined and managed by OpenAI. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `resource_type: string` - - `model: optional string` + Resource type the role is bound to (for example `api.organization` or `api.project`). - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/roles \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "permissions": [ + "string" + ], + "role_name": "role_name" + }' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +```http +curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "description": "Allows managing API keys for the project" + }' +``` - The aggregated images usage details of the specific time bucket. +#### Response - - `images: number` +```json +{ + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false +} +``` - The number of images processed. +## Delete project role - - `num_model_requests: number` +**delete** `/projects/{project_id}/roles/{role_id}` - The count of requests made to the model. +Deletes a custom role from a project. - - `object: "organization.usage.images.result"` +### Path Parameters - - `"organization.usage.images.result"` +- `project_id: string` - - `api_key_id: optional string` +- `role_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Returns - - `model: optional string` +- `id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Identifier of the deleted role. - - `project_id: optional string` +- `deleted: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether the role was deleted. - - `size: optional string` +- `object: "role.deleted"` - When `group_by=size`, this field provides the image size of the grouped usage result. + Always `role.deleted`. - - `source: optional string` + - `"role.deleted"` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. +### Example - - `user_id: optional string` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +#### Response - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +```json +{ + "id": "id", + "deleted": true, + "object": "role.deleted" +} +``` - The aggregated audio speeches usage details of the specific time bucket. +### Example - - `characters: number` +```http +curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The number of characters processed. +#### Response - - `num_model_requests: number` +```json +{ + "object": "role.deleted", + "id": "role_01J1F8PROJ", + "deleted": true +} +``` - The count of requests made to the model. +## List project roles - - `object: "organization.usage.audio_speeches.result"` +**get** `/projects/{project_id}/roles` - - `"organization.usage.audio_speeches.result"` +Lists the roles configured for a project. - - `api_key_id: optional string` +### Path Parameters - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `project_id: string` - - `model: optional string` +### Query Parameters - When `group_by=model`, this field provides the model name of the grouped usage result. +- `after: optional string` - - `project_id: optional string` + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `limit: optional number` - - `user_id: optional string` + A limit on the number of roles to return. Defaults to 1000. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `order: optional "asc" or "desc"` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + Sort order for the returned roles. - The aggregated audio transcriptions usage details of the specific time bucket. + - `"asc"` - - `num_model_requests: number` + - `"desc"` - The count of requests made to the model. +### Returns - - `object: "organization.usage.audio_transcriptions.result"` +- `data: array of Role` - - `"organization.usage.audio_transcriptions.result"` + Roles returned in the current page. - - `seconds: number` + - `id: string` - The number of seconds processed. + Identifier for the role. - - `api_key_id: optional string` + - `description: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Optional description of the role. - - `model: optional string` + - `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Unique name for the role. - - `project_id: optional string` + - `object: "role"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Always `role`. - - `user_id: optional string` + - `"role"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `permissions: array of string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + Permissions granted by the role. - The aggregated vector stores usage details of the specific time bucket. + - `predefined_role: boolean` - - `object: "organization.usage.vector_stores.result"` + Whether the role is predefined and managed by OpenAI. - - `"organization.usage.vector_stores.result"` + - `resource_type: string` - - `usage_bytes: number` + Resource type the role is bound to (for example `api.organization` or `api.project`). - The vector stores usage in bytes. +- `has_more: boolean` - - `project_id: optional string` + Whether more roles are available when paginating. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `next: string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + Cursor to fetch the next page of results, or `null` when there are no additional roles. - The aggregated code interpreter sessions usage details of the specific time bucket. +- `object: "list"` - - `num_sessions: number` + Always `list`. - The number of code interpreter sessions. + - `"list"` - - `object: "organization.usage.code_interpreter_sessions.result"` +### Example - - `"organization.usage.code_interpreter_sessions.result"` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```json +{ + "data": [ + { + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +### Example - The aggregated file search calls usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `num_requests: number` +#### Response - The count of file search calls. +```json +{ + "object": "list", + "data": [ + { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } + ], + "has_more": false, + "next": null +} +``` - - `object: "organization.usage.file_searches.result"` +## Retrieve project role - - `"organization.usage.file_searches.result"` +**get** `/projects/{project_id}/roles/{role_id}` - - `api_key_id: optional string` +Retrieves a project role. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Path Parameters - - `project_id: optional string` +- `project_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `role_id: string` - - `user_id: optional string` +### Returns - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `Role object { id, description, name, 4 more }` - - `vector_store_id: optional string` + Details about a role that can be assigned through the public Roles API. - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `id: string` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + Identifier for the role. - The aggregated web search calls usage details of the specific time bucket. + - `description: string` - - `num_model_requests: number` + Optional description of the role. - The count of model requests. + - `name: string` - - `num_requests: number` + Unique name for the role. - The count of web search calls. + - `object: "role"` - - `object: "organization.usage.web_searches.result"` + Always `role`. - - `"organization.usage.web_searches.result"` + - `"role"` - - `api_key_id: optional string` + - `permissions: array of string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Permissions granted by the role. - - `context_level: optional string` + - `predefined_role: boolean` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + Whether the role is predefined and managed by OpenAI. - - `model: optional string` + - `resource_type: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `user_id: optional string` +#### Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +### Example - The aggregated costs details of the specific time bucket. +```http +curl https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.costs.result"` +#### Response - - `"organization.costs.result"` +```json +{ + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false +} +``` - - `amount: optional object { currency, value }` +## Update project role - The monetary value in its associated currency. +**post** `/projects/{project_id}/roles/{role_id}` - - `currency: optional string` +Updates an existing project role. - Lowercase ISO-4217 currency e.g. "usd" +### Path Parameters - - `value: optional number` +- `project_id: string` - The numeric value of the cost. +- `role_id: string` - - `api_key_id: optional string` +### Body Parameters - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +- `description: optional string` - - `line_item: optional string` + New description for the role. - When `group_by=line_item`, this field provides the line item of the grouped costs result. +- `permissions: optional array of string` - - `project_id: optional string` + Updated set of permissions for the role. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +- `role_name: optional string` - - `quantity: optional number` + New name for the role. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +### Returns - - `start_time: number` +- `Role object { id, description, name, 4 more }` - - `has_more: boolean` + Details about a role that can be assigned through the public Roles API. - - `next_page: string` + - `id: string` - - `object: "page"` + Identifier for the role. - - `"page"` + - `description: string` -### Usage Audio Transcriptions Response + Optional description of the role. -- `UsageAudioTranscriptionsResponse object { data, has_more, next_page, object }` + - `name: string` - - `data: array of object { end_time, object, results, start_time }` + Unique name for the role. - - `end_time: number` + - `object: "role"` - - `object: "bucket"` + Always `role`. - - `"bucket"` + - `"role"` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `permissions: array of string` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + Permissions granted by the role. - The aggregated completions usage details of the specific time bucket. + - `predefined_role: boolean` - - `input_tokens: number` + Whether the role is predefined and managed by OpenAI. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `resource_type: string` - - `num_model_requests: number` + Resource type the role is bound to (for example `api.organization` or `api.project`). - The count of requests made to the model. +### Example - - `object: "organization.usage.completions.result"` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - - `"organization.usage.completions.result"` +#### Response - - `output_tokens: number` +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Example - - `api_key_id: optional string` +```http +curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "description": "Allows managing API keys for the project" + }' +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `batch: optional boolean` +```json +{ + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false +} +``` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +## Domain Types - - `input_audio_tokens: optional number` +### Role Delete Response - The aggregated number of uncached audio input tokens used. +- `RoleDeleteResponse object { id, deleted, object }` - - `input_cache_write_tokens: optional number` + Confirmation payload returned after deleting a role. - The aggregated number of input tokens written to the cache. + - `id: string` - - `input_cached_audio_tokens: optional number` + Identifier of the deleted role. - The aggregated number of cached audio input tokens used. + - `deleted: boolean` - - `input_cached_image_tokens: optional number` + Whether the role was deleted. - The aggregated number of cached image input tokens used. + - `object: "role.deleted"` - - `input_cached_text_tokens: optional number` + Always `role.deleted`. - The aggregated number of cached text input tokens used. + - `"role.deleted"` - - `input_cached_tokens: optional number` +# Service Accounts - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +## Create project service account - - `input_image_tokens: optional number` +**post** `/organization/projects/{project_id}/service_accounts` - The aggregated number of uncached image input tokens used. +Creates a new service account in the project. By default, this also returns an unredacted API key for the service account. - - `input_text_tokens: optional number` +### Path Parameters - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +- `project_id: string` - - `input_uncached_tokens: optional number` +### Body Parameters - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +- `name: string` - - `model: optional string` + The name of the service account being created. - When `group_by=model`, this field provides the model name of the grouped usage result. +- `create_service_account_only: optional boolean` - - `output_audio_tokens: optional number` + Create the service account without default roles or an API key. - The aggregated number of audio output tokens used. +### Returns - - `output_image_tokens: optional number` +- `id: string` - The aggregated number of image output tokens used. +- `api_key: object { id, created_at, name, 2 more }` - - `output_text_tokens: optional number` + - `id: string` - The aggregated number of text output tokens used. + - `created_at: number` - - `project_id: optional string` + - `name: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `object: "organization.project.service_account.api_key"` - - `service_tier: optional string` + The object type, which is always `organization.project.service_account.api_key` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `"organization.project.service_account.api_key"` - - `user_id: optional string` + - `value: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `created_at: number` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +- `name: string` - The aggregated embeddings usage details of the specific time bucket. +- `object: "organization.project.service_account"` - - `input_tokens: number` + - `"organization.project.service_account"` - The aggregated number of input tokens used. +- `role: "member" or "none"` - - `num_model_requests: number` + Service accounts created with default project membership have role `member`. Accounts created with `create_service_account_only` have role `none`. - The count of requests made to the model. + - `"member"` - - `object: "organization.usage.embeddings.result"` + - `"none"` - - `"organization.usage.embeddings.result"` +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "name": "name" + }' +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "id": "id", + "api_key": { + "id": "id", + "created_at": 0, + "name": "name", + "object": "organization.project.service_account.api_key", + "value": "value" + }, + "created_at": 0, + "name": "name", + "object": "organization.project.service_account", + "role": "member" +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Production App" + }' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Production App", + "role": "member", + "created_at": 1711471533, + "api_key": { + "object": "organization.project.service_account.api_key", + "value": "sk-abcdefghijklmnop123", + "name": "Secret Key", + "created_at": 1711471533, + "id": "key_abc" + } +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Delete project service account - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` +**delete** `/organization/projects/{project_id}/service_accounts/{service_account_id}` - The aggregated moderations usage details of the specific time bucket. +Deletes a service account from the project. - - `input_tokens: number` +Returns confirmation of service account deletion, or an error if the project +is archived (archived projects have no service accounts). - The aggregated number of input tokens used. +### Path Parameters - - `num_model_requests: number` +- `project_id: string` - The count of requests made to the model. +- `service_account_id: string` - - `object: "organization.usage.moderations.result"` +### Returns - - `"organization.usage.moderations.result"` +- `id: string` - - `api_key_id: optional string` +- `deleted: boolean` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `object: "organization.project.service_account.deleted"` - - `model: optional string` + - `"organization.project.service_account.deleted"` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "id": "id", + "deleted": true, + "object": "organization.project.service_account.deleted" +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated images usage details of the specific time bucket. +#### Response - - `images: number` +```json +{ + "object": "organization.project.service_account.deleted", + "id": "svc_acct_abc", + "deleted": true +} +``` - The number of images processed. +## List project service accounts - - `num_model_requests: number` +**get** `/organization/projects/{project_id}/service_accounts` - The count of requests made to the model. +Returns a list of service accounts in the project. - - `object: "organization.usage.images.result"` +### Path Parameters - - `"organization.usage.images.result"` +- `project_id: string` - - `api_key_id: optional string` +### Query Parameters - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `after: optional string` - - `model: optional string` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - When `group_by=model`, this field provides the model name of the grouped usage result. +- `limit: optional number` - - `project_id: optional string` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Returns - - `size: optional string` +- `data: array of ProjectServiceAccount` - When `group_by=size`, this field provides the image size of the grouped usage result. + - `id: string` - - `source: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `created_at: number` - - `user_id: optional string` + The Unix timestamp (in seconds) of when the service account was created - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `name: string` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + The name of the service account - The aggregated audio speeches usage details of the specific time bucket. + - `object: "organization.project.service_account"` - - `characters: number` + The object type, which is always `organization.project.service_account` - The number of characters processed. + - `"organization.project.service_account"` - - `num_model_requests: number` + - `role: "owner" or "member" or "none"` - The count of requests made to the model. + `owner`, `member`, or `none` - - `object: "organization.usage.audio_speeches.result"` + - `"owner"` - - `"organization.usage.audio_speeches.result"` + - `"member"` - - `api_key_id: optional string` + - `"none"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `has_more: boolean` - - `model: optional string` +- `object: "list"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"list"` - - `project_id: optional string` +- `first_id: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `last_id: optional string` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +#### Response - The aggregated audio transcriptions usage details of the specific time bucket. +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "name": "name", + "object": "organization.project.service_account", + "role": "owner" + } + ], + "has_more": true, + "object": "list", + "first_id": "first_id", + "last_id": "last_id" +} +``` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.audio_transcriptions.result"` +#### Response - - `"organization.usage.audio_transcriptions.result"` +```json +{ + "object": "list", + "data": [ + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + ], + "first_id": "svc_acct_abc", + "last_id": "svc_acct_xyz", + "has_more": false +} +``` - - `seconds: number` +## Retrieve project service account - The number of seconds processed. +**get** `/organization/projects/{project_id}/service_accounts/{service_account_id}` - - `api_key_id: optional string` +Retrieves a service account in the project. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Path Parameters - - `model: optional string` +- `project_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. +- `service_account_id: string` - - `project_id: optional string` +### Returns - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `ProjectServiceAccount object { id, created_at, name, 2 more }` - - `user_id: optional string` + Represents an individual service account in a project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + The identifier, which can be referenced in API endpoints - The aggregated vector stores usage details of the specific time bucket. + - `created_at: number` - - `object: "organization.usage.vector_stores.result"` + The Unix timestamp (in seconds) of when the service account was created - - `"organization.usage.vector_stores.result"` + - `name: string` - - `usage_bytes: number` + The name of the service account - The vector stores usage in bytes. + - `object: "organization.project.service_account"` - - `project_id: optional string` + The object type, which is always `organization.project.service_account` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.project.service_account"` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `role: "owner" or "member" or "none"` - The aggregated code interpreter sessions usage details of the specific time bucket. + `owner`, `member`, or `none` - - `num_sessions: number` + - `"owner"` - The number of code interpreter sessions. + - `"member"` - - `object: "organization.usage.code_interpreter_sessions.result"` + - `"none"` - - `"organization.usage.code_interpreter_sessions.result"` +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +```json +{ + "id": "id", + "created_at": 0, + "name": "name", + "object": "organization.project.service_account", + "role": "owner" +} +``` - The aggregated file search calls usage details of the specific time bucket. +### Example - - `num_requests: number` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The count of file search calls. +#### Response - - `object: "organization.usage.file_searches.result"` +```json +{ + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 +} +``` - - `"organization.usage.file_searches.result"` +## Update project service account - - `api_key_id: optional string` +**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +Updates a service account in the project. - - `project_id: optional string` +### Path Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `project_id: string` - - `user_id: optional string` +- `service_account_id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Body Parameters - - `vector_store_id: optional string` +- `name: optional string` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + The updated service account name. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +- `role: optional "member" or "owner"` - The aggregated web search calls usage details of the specific time bucket. + The updated service account role. - - `num_model_requests: number` + - `"member"` - The count of model requests. + - `"owner"` - - `num_requests: number` +### Returns - The count of web search calls. +- `ProjectServiceAccount object { id, created_at, name, 2 more }` - - `object: "organization.usage.web_searches.result"` + Represents an individual service account in a project. - - `"organization.usage.web_searches.result"` + - `id: string` - - `api_key_id: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `created_at: number` - - `context_level: optional string` + The Unix timestamp (in seconds) of when the service account was created - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + - `name: string` - - `model: optional string` + The name of the service account - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "organization.project.service_account"` - - `project_id: optional string` + The object type, which is always `organization.project.service_account` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.project.service_account"` - - `user_id: optional string` + - `role: "owner" or "member" or "none"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + `owner`, `member`, or `none` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `"owner"` - The aggregated costs details of the specific time bucket. + - `"member"` - - `object: "organization.costs.result"` + - `"none"` - - `"organization.costs.result"` +### Example - - `amount: optional object { currency, value }` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - The monetary value in its associated currency. +#### Response - - `currency: optional string` +```json +{ + "id": "id", + "created_at": 0, + "name": "name", + "object": "organization.project.service_account", + "role": "owner" +} +``` - Lowercase ISO-4217 currency e.g. "usd" +### Example - - `value: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Updated service account", + "role": "member" + }' +``` - The numeric value of the cost. +#### Response - - `api_key_id: optional string` +```json +{ + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Updated service account", + "role": "member", + "created_at": 1711471533 +} +``` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +## Domain Types - - `line_item: optional string` +### Project Service Account - When `group_by=line_item`, this field provides the line item of the grouped costs result. +- `ProjectServiceAccount object { id, created_at, name, 2 more }` - - `project_id: optional string` + Represents an individual service account in a project. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `id: string` - - `quantity: optional number` + The identifier, which can be referenced in API endpoints - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `created_at: number` - - `start_time: number` + The Unix timestamp (in seconds) of when the service account was created - - `has_more: boolean` + - `name: string` - - `next_page: string` + The name of the service account - - `object: "page"` + - `object: "organization.project.service_account"` - - `"page"` + The object type, which is always `organization.project.service_account` -### Usage Code Interpreter Sessions Response + - `"organization.project.service_account"` -- `UsageCodeInterpreterSessionsResponse object { data, has_more, next_page, object }` + - `role: "owner" or "member" or "none"` - - `data: array of object { end_time, object, results, start_time }` + `owner`, `member`, or `none` - - `end_time: number` + - `"owner"` - - `object: "bucket"` + - `"member"` - - `"bucket"` + - `"none"` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +### Service Account Create Response - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +- `ServiceAccountCreateResponse object { id, api_key, created_at, 3 more }` - The aggregated completions usage details of the specific time bucket. + - `id: string` - - `input_tokens: number` + - `api_key: object { id, created_at, name, 2 more }` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `id: string` - - `num_model_requests: number` + - `created_at: number` - The count of requests made to the model. + - `name: string` - - `object: "organization.usage.completions.result"` + - `object: "organization.project.service_account.api_key"` - - `"organization.usage.completions.result"` + The object type, which is always `organization.project.service_account.api_key` - - `output_tokens: number` + - `"organization.project.service_account.api_key"` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `value: string` - - `api_key_id: optional string` + - `created_at: number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `name: string` - - `batch: optional boolean` + - `object: "organization.project.service_account"` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `"organization.project.service_account"` - - `input_audio_tokens: optional number` + - `role: "member" or "none"` - The aggregated number of uncached audio input tokens used. + Service accounts created with default project membership have role `member`. Accounts created with `create_service_account_only` have role `none`. - - `input_cache_write_tokens: optional number` + - `"member"` - The aggregated number of input tokens written to the cache. + - `"none"` - - `input_cached_audio_tokens: optional number` +### Service Account Delete Response - The aggregated number of cached audio input tokens used. +- `ServiceAccountDeleteResponse object { id, deleted, object }` - - `input_cached_image_tokens: optional number` + - `id: string` - The aggregated number of cached image input tokens used. + - `deleted: boolean` - - `input_cached_text_tokens: optional number` + - `object: "organization.project.service_account.deleted"` - The aggregated number of cached text input tokens used. + - `"organization.project.service_account.deleted"` - - `input_cached_tokens: optional number` +# API Keys - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +## Create project service account API key - - `input_image_tokens: optional number` +**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys` - The aggregated number of uncached image input tokens used. +Creates an API key for a service account in the project. - - `input_text_tokens: optional number` +### Path Parameters - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +- `project_id: string` - - `input_uncached_tokens: optional number` + The ID of the project. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +- `service_account_id: string` - - `model: optional string` + The ID of the service account. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Body Parameters - - `output_audio_tokens: optional number` +- `name: optional string` - The aggregated number of audio output tokens used. + API key name. - - `output_image_tokens: optional number` +- `scopes: optional array of string` - The aggregated number of image output tokens used. + API key scopes. - - `output_text_tokens: optional number` +### Returns - The aggregated number of text output tokens used. +- `id: string` - - `project_id: optional string` + The identifier of the API key. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `created_at: number` - - `service_tier: optional string` + The Unix timestamp (in seconds) when the API key was created. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +- `name: string` - - `user_id: optional string` + The name of the API key. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `object: "organization.project.service_account.api_key"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + The object type, which is always `organization.project.service_account.api_key` - The aggregated embeddings usage details of the specific time bucket. + - `"organization.project.service_account.api_key"` - - `input_tokens: number` +- `value: string` - The aggregated number of input tokens used. + The unredacted API key value. - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys \ + -X POST \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `object: "organization.usage.embeddings.result"` +#### Response - - `"organization.usage.embeddings.result"` +```json +{ + "id": "id", + "created_at": 0, + "name": "name", + "object": "organization.project.service_account.api_key", + "value": "value" +} +``` - - `api_key_id: optional string` +### Example - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc/api_keys \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Production App", + "scopes": ["api.responses.write"] + }' +``` - - `model: optional string` +#### Response - When `group_by=model`, this field provides the model name of the grouped usage result. +```json +{ + "object": "organization.project.service_account.api_key", + "value": "sk-abcdefghijklmnop123", + "name": "Production App", + "created_at": 1711471533, + "id": "key_abc" +} +``` - - `project_id: optional string` +## Domain Types - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### API Key Create Response - - `user_id: optional string` +- `APIKeyCreateResponse object { id, created_at, name, 2 more }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + The identifier of the API key. - The aggregated moderations usage details of the specific time bucket. + - `created_at: number` - - `input_tokens: number` + The Unix timestamp (in seconds) when the API key was created. - The aggregated number of input tokens used. + - `name: string` - - `num_model_requests: number` + The name of the API key. - The count of requests made to the model. + - `object: "organization.project.service_account.api_key"` - - `object: "organization.usage.moderations.result"` + The object type, which is always `organization.project.service_account.api_key` - - `"organization.usage.moderations.result"` + - `"organization.project.service_account.api_key"` - - `api_key_id: optional string` + - `value: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The unredacted API key value. - - `model: optional string` +# Spend Alerts - When `group_by=model`, this field provides the model name of the grouped usage result. +## Create project spend alert - - `project_id: optional string` +**post** `/organization/projects/{project_id}/spend_alerts` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Creates a project spend alert. - - `user_id: optional string` +### Path Parameters - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `project_id: string` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +### Body Parameters - The aggregated images usage details of the specific time bucket. +- `currency: "USD"` - - `images: number` + The currency for the threshold amount. - The number of images processed. + - `"USD"` - - `num_model_requests: number` +- `interval: "month"` - The count of requests made to the model. + The time interval for evaluating spend against the threshold. - - `object: "organization.usage.images.result"` + - `"month"` - - `"organization.usage.images.result"` +- `notification_channel: object { recipients, type, subject_prefix }` - - `api_key_id: optional string` + Email notification settings for a spend alert. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `recipients: array of string` - - `model: optional string` + Email addresses that receive the spend alert notification. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `type: "email"` - - `project_id: optional string` + The notification channel type. Currently only `email` is supported. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"email"` - - `size: optional string` + - `subject_prefix: optional string` - When `group_by=size`, this field provides the image size of the grouped usage result. + Optional subject prefix for alert emails. - - `source: optional string` +- `threshold_amount: number` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + The alert threshold amount, in cents. - - `user_id: optional string` +### Returns - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `ProjectSpendAlert object { id, currency, interval, 3 more }` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + Represents a spend alert configured at the project level. - The aggregated audio speeches usage details of the specific time bucket. + - `id: string` - - `characters: number` + The identifier, which can be referenced in API endpoints. - The number of characters processed. + - `currency: "USD"` - - `num_model_requests: number` + The currency for the threshold amount. - The count of requests made to the model. + - `"USD"` - - `object: "organization.usage.audio_speeches.result"` + - `interval: "month"` - - `"organization.usage.audio_speeches.result"` + The time interval for evaluating spend against the threshold. - - `api_key_id: optional string` + - `"month"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `notification_channel: object { recipients, type, subject_prefix }` - - `model: optional string` + Email notification settings for a spend alert. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `recipients: array of string` - - `project_id: optional string` + Email addresses that receive the spend alert notification. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `type: "email"` - - `user_id: optional string` + The notification channel type. Currently only `email` is supported. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"email"` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `subject_prefix: optional string` - The aggregated audio transcriptions usage details of the specific time bucket. + Optional subject prefix for alert emails. - - `num_model_requests: number` + - `object: "project.spend_alert"` - The count of requests made to the model. + The object type, which is always `project.spend_alert`. - - `object: "organization.usage.audio_transcriptions.result"` + - `"project.spend_alert"` - - `"organization.usage.audio_transcriptions.result"` + - `threshold_amount: number` - - `seconds: number` + The alert threshold amount, in cents. - The number of seconds processed. +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email" + }, + "threshold_amount": 0 + }' +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "project.spend_alert", + "threshold_amount": 0 +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + }' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "id": "alert_abc123", + "object": "project.spend_alert", + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Delete project spend alert - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +**delete** `/organization/projects/{project_id}/spend_alerts/{alert_id}` - The aggregated vector stores usage details of the specific time bucket. +Deletes a project spend alert. - - `object: "organization.usage.vector_stores.result"` +### Path Parameters - - `"organization.usage.vector_stores.result"` +- `project_id: string` - - `usage_bytes: number` +- `alert_id: string` - The vector stores usage in bytes. +### Returns - - `project_id: optional string` +- `ProjectSpendAlertDeleted object { id, deleted, object }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Confirmation payload returned after deleting a project spend alert. - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `id: string` - The aggregated code interpreter sessions usage details of the specific time bucket. + The deleted spend alert ID. - - `num_sessions: number` + - `deleted: boolean` - The number of code interpreter sessions. + Whether the spend alert was deleted. - - `object: "organization.usage.code_interpreter_sessions.result"` + - `object: "project.spend_alert.deleted"` - - `"organization.usage.code_interpreter_sessions.result"` + Always `project.spend_alert.deleted`. - - `project_id: optional string` + - `"project.spend_alert.deleted"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Example - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated file search calls usage details of the specific time bucket. +#### Response - - `num_requests: number` +```json +{ + "id": "id", + "deleted": true, + "object": "project.spend_alert.deleted" +} +``` - The count of file search calls. +### Example - - `object: "organization.usage.file_searches.result"` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"organization.usage.file_searches.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "id": "alert_abc123", + "object": "project.spend_alert.deleted", + "deleted": true +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +## List project spend alerts - - `project_id: optional string` +**get** `/organization/projects/{project_id}/spend_alerts` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Lists project spend alerts. - - `user_id: optional string` +### Path Parameters - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `project_id: string` - - `vector_store_id: optional string` +### Query Parameters - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +- `after: optional string` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page. - The aggregated web search calls usage details of the specific time bucket. +- `before: optional string` - - `num_model_requests: number` + Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page. - The count of model requests. +- `limit: optional number` - - `num_requests: number` + A limit on the number of spend alerts to return. Defaults to 20. - The count of web search calls. +- `order: optional "asc" or "desc"` - - `object: "organization.usage.web_searches.result"` + Sort order for the returned spend alerts. - - `"organization.usage.web_searches.result"` + - `"asc"` - - `api_key_id: optional string` + - `"desc"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Returns - - `context_level: optional string` +- `data: array of ProjectSpendAlert` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + Spend alerts returned in the current page. - - `model: optional string` + - `id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + The identifier, which can be referenced in API endpoints. - - `project_id: optional string` + - `currency: "USD"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The currency for the threshold amount. - - `user_id: optional string` + - `"USD"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `interval: "month"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + The time interval for evaluating spend against the threshold. - The aggregated costs details of the specific time bucket. + - `"month"` - - `object: "organization.costs.result"` + - `notification_channel: object { recipients, type, subject_prefix }` - - `"organization.costs.result"` + Email notification settings for a spend alert. - - `amount: optional object { currency, value }` + - `recipients: array of string` - The monetary value in its associated currency. + Email addresses that receive the spend alert notification. - - `currency: optional string` + - `type: "email"` - Lowercase ISO-4217 currency e.g. "usd" + The notification channel type. Currently only `email` is supported. - - `value: optional number` + - `"email"` - The numeric value of the cost. + - `subject_prefix: optional string` - - `api_key_id: optional string` + Optional subject prefix for alert emails. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `object: "project.spend_alert"` - - `line_item: optional string` + The object type, which is always `project.spend_alert`. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `"project.spend_alert"` - - `project_id: optional string` + - `threshold_amount: number` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + The alert threshold amount, in cents. - - `quantity: optional number` +- `first_id: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + The ID of the first spend alert in this page. - - `start_time: number` +- `has_more: boolean` - - `has_more: boolean` + Whether more spend alerts are available when paginating. - - `next_page: string` +- `last_id: string` - - `object: "page"` + The ID of the last spend alert in this page. - - `"page"` +- `object: "list"` -### Usage Completions Response + Always `list`. -- `UsageCompletionsResponse object { data, has_more, next_page, object }` + - `"list"` - - `data: array of object { end_time, object, results, start_time }` +### Example - - `end_time: number` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `object: "bucket"` +#### Response - - `"bucket"` +```json +{ + "data": [ + { + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "project.spend_alert", + "threshold_amount": 0 + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +### Example - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts?limit=20&order=asc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated completions usage details of the specific time bucket. +#### Response - - `input_tokens: number` +```json +{ + "object": "list", + "data": [ + { + "id": "alert_abc123", + "object": "project.spend_alert", + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + } + ], + "first_id": "alert_abc123", + "last_id": "alert_abc123", + "has_more": false +} +``` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +## Retrieve project spend alert - - `num_model_requests: number` +**get** `/organization/projects/{project_id}/spend_alerts/{alert_id}` - The count of requests made to the model. +Retrieves a project spend alert. - - `object: "organization.usage.completions.result"` +### Path Parameters - - `"organization.usage.completions.result"` +- `project_id: string` - - `output_tokens: number` +- `alert_id: string` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Returns - - `api_key_id: optional string` +- `ProjectSpendAlert object { id, currency, interval, 3 more }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Represents a spend alert configured at the project level. - - `batch: optional boolean` + - `id: string` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + The identifier, which can be referenced in API endpoints. - - `input_audio_tokens: optional number` + - `currency: "USD"` - The aggregated number of uncached audio input tokens used. + The currency for the threshold amount. - - `input_cache_write_tokens: optional number` + - `"USD"` - The aggregated number of input tokens written to the cache. + - `interval: "month"` - - `input_cached_audio_tokens: optional number` + The time interval for evaluating spend against the threshold. - The aggregated number of cached audio input tokens used. + - `"month"` - - `input_cached_image_tokens: optional number` + - `notification_channel: object { recipients, type, subject_prefix }` - The aggregated number of cached image input tokens used. + Email notification settings for a spend alert. - - `input_cached_text_tokens: optional number` + - `recipients: array of string` - The aggregated number of cached text input tokens used. + Email addresses that receive the spend alert notification. - - `input_cached_tokens: optional number` + - `type: "email"` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The notification channel type. Currently only `email` is supported. - - `input_image_tokens: optional number` + - `"email"` - The aggregated number of uncached image input tokens used. + - `subject_prefix: optional string` - - `input_text_tokens: optional number` + Optional subject prefix for alert emails. - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `object: "project.spend_alert"` - - `input_uncached_tokens: optional number` + The object type, which is always `project.spend_alert`. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + - `"project.spend_alert"` - - `model: optional string` + - `threshold_amount: number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The alert threshold amount, in cents. - - `output_audio_tokens: optional number` +### Example - The aggregated number of audio output tokens used. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `output_image_tokens: optional number` +#### Response - The aggregated number of image output tokens used. +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "project.spend_alert", + "threshold_amount": 0 +} +``` - - `output_text_tokens: optional number` +### Example - The aggregated number of text output tokens used. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```json +{ + "id": "alert_abc123", + "object": "project.spend_alert", + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - - `service_tier: optional string` +## Update project spend alert - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +**post** `/organization/projects/{project_id}/spend_alerts/{alert_id}` - - `user_id: optional string` +Updates a project spend alert. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Path Parameters - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +- `project_id: string` - The aggregated embeddings usage details of the specific time bucket. +- `alert_id: string` - - `input_tokens: number` +### Body Parameters - The aggregated number of input tokens used. +- `currency: "USD"` - - `num_model_requests: number` + The currency for the threshold amount. - The count of requests made to the model. + - `"USD"` - - `object: "organization.usage.embeddings.result"` +- `interval: "month"` - - `"organization.usage.embeddings.result"` + The time interval for evaluating spend against the threshold. - - `api_key_id: optional string` + - `"month"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `notification_channel: object { recipients, type, subject_prefix }` - - `model: optional string` + Email notification settings for a spend alert. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `recipients: array of string` - - `project_id: optional string` + Email addresses that receive the spend alert notification. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `type: "email"` - - `user_id: optional string` + The notification channel type. Currently only `email` is supported. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"email"` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `subject_prefix: optional string` - The aggregated moderations usage details of the specific time bucket. + Optional subject prefix for alert emails. - - `input_tokens: number` +- `threshold_amount: number` - The aggregated number of input tokens used. + The alert threshold amount, in cents. - - `num_model_requests: number` +### Returns - The count of requests made to the model. +- `ProjectSpendAlert object { id, currency, interval, 3 more }` - - `object: "organization.usage.moderations.result"` + Represents a spend alert configured at the project level. - - `"organization.usage.moderations.result"` + - `id: string` - - `api_key_id: optional string` + The identifier, which can be referenced in API endpoints. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `currency: "USD"` - - `model: optional string` + The currency for the threshold amount. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"USD"` - - `project_id: optional string` + - `interval: "month"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The time interval for evaluating spend against the threshold. - - `user_id: optional string` + - `"month"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `notification_channel: object { recipients, type, subject_prefix }` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + Email notification settings for a spend alert. - The aggregated images usage details of the specific time bucket. + - `recipients: array of string` - - `images: number` + Email addresses that receive the spend alert notification. - The number of images processed. + - `type: "email"` - - `num_model_requests: number` + The notification channel type. Currently only `email` is supported. - The count of requests made to the model. + - `"email"` - - `object: "organization.usage.images.result"` + - `subject_prefix: optional string` - - `"organization.usage.images.result"` + Optional subject prefix for alert emails. - - `api_key_id: optional string` + - `object: "project.spend_alert"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The object type, which is always `project.spend_alert`. - - `model: optional string` + - `"project.spend_alert"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `threshold_amount: number` - - `project_id: optional string` + The alert threshold amount, in cents. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Example - - `size: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email" + }, + "threshold_amount": 0 + }' +``` - When `group_by=size`, this field provides the image size of the grouped usage result. +#### Response - - `source: optional string` +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "project.spend_alert", + "threshold_amount": 0 +} +``` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. +### Example - - `user_id: optional string` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + }' +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +#### Response - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +```json +{ + "id": "alert_abc123", + "object": "project.spend_alert", + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - The aggregated audio speeches usage details of the specific time bucket. +## Domain Types - - `characters: number` +### Project Spend Alert - The number of characters processed. +- `ProjectSpendAlert object { id, currency, interval, 3 more }` - - `num_model_requests: number` + Represents a spend alert configured at the project level. - The count of requests made to the model. + - `id: string` - - `object: "organization.usage.audio_speeches.result"` + The identifier, which can be referenced in API endpoints. - - `"organization.usage.audio_speeches.result"` + - `currency: "USD"` - - `api_key_id: optional string` + The currency for the threshold amount. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"USD"` - - `model: optional string` + - `interval: "month"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The time interval for evaluating spend against the threshold. - - `project_id: optional string` + - `"month"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `notification_channel: object { recipients, type, subject_prefix }` - - `user_id: optional string` + Email notification settings for a spend alert. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `recipients: array of string` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + Email addresses that receive the spend alert notification. - The aggregated audio transcriptions usage details of the specific time bucket. + - `type: "email"` - - `num_model_requests: number` + The notification channel type. Currently only `email` is supported. - The count of requests made to the model. + - `"email"` - - `object: "organization.usage.audio_transcriptions.result"` + - `subject_prefix: optional string` - - `"organization.usage.audio_transcriptions.result"` + Optional subject prefix for alert emails. - - `seconds: number` + - `object: "project.spend_alert"` - The number of seconds processed. + The object type, which is always `project.spend_alert`. - - `api_key_id: optional string` + - `"project.spend_alert"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `threshold_amount: number` - - `model: optional string` + The alert threshold amount, in cents. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Project Spend Alert Deleted - - `project_id: optional string` +- `ProjectSpendAlertDeleted object { id, deleted, object }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Confirmation payload returned after deleting a project spend alert. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The deleted spend alert ID. - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + - `deleted: boolean` - The aggregated vector stores usage details of the specific time bucket. + Whether the spend alert was deleted. - - `object: "organization.usage.vector_stores.result"` + - `object: "project.spend_alert.deleted"` - - `"organization.usage.vector_stores.result"` + Always `project.spend_alert.deleted`. - - `usage_bytes: number` + - `"project.spend_alert.deleted"` - The vector stores usage in bytes. +# Spend Limit - - `project_id: optional string` +## Delete project spend limit - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**delete** `/organization/projects/{project_id}/spend_limit` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +Delete a project's hard spend limit. - The aggregated code interpreter sessions usage details of the specific time bucket. +### Path Parameters - - `num_sessions: number` +- `project_id: string` - The number of code interpreter sessions. +### Returns - - `object: "organization.usage.code_interpreter_sessions.result"` +- `ProjectSpendLimitDeleted object { deleted, object }` - - `"organization.usage.code_interpreter_sessions.result"` + Confirmation payload returned after deleting a project hard spend limit. - - `project_id: optional string` + - `deleted: boolean` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether the hard spend limit was deleted. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `object: "project.spend_limit.deleted"` - The aggregated file search calls usage details of the specific time bucket. + The object type, which is always `project.spend_limit.deleted`. - - `num_requests: number` + - `"project.spend_limit.deleted"` - The count of file search calls. +### Example - - `object: "organization.usage.file_searches.result"` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"organization.usage.file_searches.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "deleted": true, + "object": "project.spend_limit.deleted" +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "object": "project.spend_limit.deleted", + "deleted": true +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Retrieve project spend limit - - `vector_store_id: optional string` +**get** `/organization/projects/{project_id}/spend_limit` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +Get a project's hard spend limit. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +### Path Parameters - The aggregated web search calls usage details of the specific time bucket. +- `project_id: string` - - `num_model_requests: number` +### Returns - The count of model requests. +- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` - - `num_requests: number` + Represents a hard spend limit configured at the project level. - The count of web search calls. + - `currency: string or "USD"` - - `object: "organization.usage.web_searches.result"` + The currency for the threshold amount. Currently, only `USD` is supported. - - `"organization.usage.web_searches.result"` + - `string` - - `api_key_id: optional string` + - `"USD"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"USD"` - - `context_level: optional string` + - `enforcement: object { status }` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + The current enforcement state of the hard spend limit. - - `model: optional string` + - `status: string or "inactive" or "enforcing"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the hard spend limit is currently enforcing. - - `project_id: optional string` + - `string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"inactive" or "enforcing"` - - `user_id: optional string` + Whether the hard spend limit is currently enforcing. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"inactive"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `"enforcing"` - The aggregated costs details of the specific time bucket. + - `interval: string or "month"` - - `object: "organization.costs.result"` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - - `"organization.costs.result"` + - `string` - - `amount: optional object { currency, value }` + - `"month"` - The monetary value in its associated currency. + - `"month"` - - `currency: optional string` + - `object: "project.spend_limit"` - Lowercase ISO-4217 currency e.g. "usd" + The object type, which is always `project.spend_limit`. - - `value: optional number` + - `"project.spend_limit"` - The numeric value of the cost. + - `threshold_amount: number` - - `api_key_id: optional string` + The hard spend limit amount, in cents. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +### Example - - `line_item: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=line_item`, this field provides the line item of the grouped costs result. +#### Response - - `project_id: optional string` +```json +{ + "currency": "USD", + "enforcement": { + "status": "inactive" + }, + "interval": "month", + "object": "project.spend_limit", + "threshold_amount": 0 +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +### Example - - `quantity: optional number` +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +#### Response - - `start_time: number` +```json +{ + "object": "project.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } +} +``` - - `has_more: boolean` +## Update project spend limit - - `next_page: string` +**post** `/organization/projects/{project_id}/spend_limit` - - `object: "page"` +Create or replace a project's hard spend limit. - - `"page"` +### Path Parameters -### Usage Embeddings Response +- `project_id: string` -- `UsageEmbeddingsResponse object { data, has_more, next_page, object }` +### Body Parameters - - `data: array of object { end_time, object, results, start_time }` +- `currency: "USD"` - - `end_time: number` + The currency for the threshold amount. Currently, only `USD` is supported. - - `object: "bucket"` + - `"USD"` - - `"bucket"` +- `interval: "month"` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `"month"` - The aggregated completions usage details of the specific time bucket. +- `threshold_amount: number` - - `input_tokens: number` + The hard spend limit amount, in cents. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Returns - - `num_model_requests: number` +- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` - The count of requests made to the model. + Represents a hard spend limit configured at the project level. - - `object: "organization.usage.completions.result"` + - `currency: string or "USD"` - - `"organization.usage.completions.result"` + The currency for the threshold amount. Currently, only `USD` is supported. - - `output_tokens: number` + - `string` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `"USD"` - - `api_key_id: optional string` + - `"USD"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `enforcement: object { status }` - - `batch: optional boolean` + The current enforcement state of the hard spend limit. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `status: string or "inactive" or "enforcing"` - - `input_audio_tokens: optional number` + Whether the hard spend limit is currently enforcing. - The aggregated number of uncached audio input tokens used. + - `string` - - `input_cache_write_tokens: optional number` + - `"inactive" or "enforcing"` - The aggregated number of input tokens written to the cache. + Whether the hard spend limit is currently enforcing. - - `input_cached_audio_tokens: optional number` + - `"inactive"` - The aggregated number of cached audio input tokens used. + - `"enforcing"` - - `input_cached_image_tokens: optional number` + - `interval: string or "month"` - The aggregated number of cached image input tokens used. + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - - `input_cached_text_tokens: optional number` + - `string` - The aggregated number of cached text input tokens used. + - `"month"` - - `input_cached_tokens: optional number` + - `"month"` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `object: "project.spend_limit"` - - `input_image_tokens: optional number` + The object type, which is always `project.spend_limit`. - The aggregated number of uncached image input tokens used. + - `"project.spend_limit"` - - `input_text_tokens: optional number` + - `threshold_amount: number` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + The hard spend limit amount, in cents. - - `input_uncached_tokens: optional number` +### Example - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "threshold_amount": 1 + }' +``` - - `model: optional string` +#### Response - When `group_by=model`, this field provides the model name of the grouped usage result. +```json +{ + "currency": "USD", + "enforcement": { + "status": "inactive" + }, + "interval": "month", + "object": "project.spend_limit", + "threshold_amount": 0 +} +``` - - `output_audio_tokens: optional number` +### Example - The aggregated number of audio output tokens used. +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 10000, + "currency": "USD", + "interval": "month" + }' +``` - - `output_image_tokens: optional number` +#### Response - The aggregated number of image output tokens used. +```json +{ + "object": "project.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } +} +``` - - `output_text_tokens: optional number` +## Domain Types - The aggregated number of text output tokens used. +### Project Spend Limit - - `project_id: optional string` +- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Represents a hard spend limit configured at the project level. - - `service_tier: optional string` + - `currency: string or "USD"` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + The currency for the threshold amount. Currently, only `USD` is supported. - - `user_id: optional string` + - `string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"USD"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + - `"USD"` - The aggregated embeddings usage details of the specific time bucket. + - `enforcement: object { status }` - - `input_tokens: number` + The current enforcement state of the hard spend limit. - The aggregated number of input tokens used. + - `status: string or "inactive" or "enforcing"` - - `num_model_requests: number` + Whether the hard spend limit is currently enforcing. - The count of requests made to the model. + - `string` - - `object: "organization.usage.embeddings.result"` + - `"inactive" or "enforcing"` - - `"organization.usage.embeddings.result"` + Whether the hard spend limit is currently enforcing. - - `api_key_id: optional string` + - `"inactive"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"enforcing"` - - `model: optional string` + - `interval: string or "month"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - - `project_id: optional string` + - `string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"month"` - - `user_id: optional string` + - `"month"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `object: "project.spend_limit"` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + The object type, which is always `project.spend_limit`. - The aggregated moderations usage details of the specific time bucket. + - `"project.spend_limit"` - - `input_tokens: number` + - `threshold_amount: number` - The aggregated number of input tokens used. + The hard spend limit amount, in cents. - - `num_model_requests: number` +### Project Spend Limit Deleted - The count of requests made to the model. +- `ProjectSpendLimitDeleted object { deleted, object }` - - `object: "organization.usage.moderations.result"` + Confirmation payload returned after deleting a project hard spend limit. - - `"organization.usage.moderations.result"` + - `deleted: boolean` - - `api_key_id: optional string` + Whether the hard spend limit was deleted. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `object: "project.spend_limit.deleted"` - - `model: optional string` + The object type, which is always `project.spend_limit.deleted`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"project.spend_limit.deleted"` - - `project_id: optional string` +# Users - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## Create project user - - `user_id: optional string` +**post** `/organization/projects/{project_id}/users` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Adds a user to the project. Users must already be members of the organization to be added to a project. - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +### Path Parameters - The aggregated images usage details of the specific time bucket. +- `project_id: string` - - `images: number` +### Body Parameters - The number of images processed. +- `role: string` - - `num_model_requests: number` + `owner` or `member` - The count of requests made to the model. +- `email: optional string` - - `object: "organization.usage.images.result"` + Email of the user to add. - - `"organization.usage.images.result"` +- `user_id: optional string` - - `api_key_id: optional string` + The ID of the user. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Returns - - `model: optional string` +- `ProjectUser object { id, added_at, object, 3 more }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Represents an individual user in a project. - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `size: optional string` + - `added_at: number` - When `group_by=size`, this field provides the image size of the grouped usage result. + The Unix timestamp (in seconds) of when the project was added. - - `source: optional string` + - `object: "organization.project.user"` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + The object type, which is always `organization.project.user` - - `user_id: optional string` + - `"organization.project.user"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `role: string` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + `owner` or `member` - The aggregated audio speeches usage details of the specific time bucket. + - `email: optional string` - - `characters: number` + The email address of the user - The number of characters processed. + - `name: optional string` - - `num_model_requests: number` + The name of the user - The count of requests made to the model. +### Example - - `object: "organization.usage.audio_speeches.result"` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "role": "role" + }' +``` - - `"organization.usage.audio_speeches.result"` +#### Response - - `api_key_id: optional string` +```json +{ + "id": "id", + "added_at": 0, + "object": "organization.project.user", + "role": "role", + "email": "email", + "name": "name" +} +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `model: optional string` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": "user_abc", + "role": "member" + }' +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "object": "organization.project.user", + "id": "user_abc", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## Delete project user - - `user_id: optional string` +**delete** `/organization/projects/{project_id}/users/{user_id}` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Deletes a user from the project. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +Returns confirmation of project user deletion, or an error if the project is +archived (archived projects have no users). - The aggregated audio transcriptions usage details of the specific time bucket. +### Path Parameters - - `num_model_requests: number` +- `project_id: string` - The count of requests made to the model. +- `user_id: string` - - `object: "organization.usage.audio_transcriptions.result"` +### Returns - - `"organization.usage.audio_transcriptions.result"` +- `id: string` - - `seconds: number` +- `deleted: boolean` - The number of seconds processed. +- `object: "organization.project.user.deleted"` - - `api_key_id: optional string` + - `"organization.project.user.deleted"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Example - - `model: optional string` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "id": "id", + "deleted": true, + "object": "organization.project.user.deleted" +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Example - - `user_id: optional string` +```http +curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +#### Response - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +```json +{ + "object": "organization.project.user.deleted", + "id": "user_abc", + "deleted": true +} +``` - The aggregated vector stores usage details of the specific time bucket. +## List project users - - `object: "organization.usage.vector_stores.result"` +**get** `/organization/projects/{project_id}/users` - - `"organization.usage.vector_stores.result"` +Returns a list of users in the project. - - `usage_bytes: number` +### Path Parameters - The vector stores usage in bytes. +- `project_id: string` - - `project_id: optional string` +### Query Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `after: optional string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - The aggregated code interpreter sessions usage details of the specific time bucket. +- `limit: optional number` - - `num_sessions: number` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - The number of code interpreter sessions. +### Returns - - `object: "organization.usage.code_interpreter_sessions.result"` +- `data: array of ProjectUser` - - `"organization.usage.code_interpreter_sessions.result"` + - `id: string` - - `project_id: optional string` + The identifier, which can be referenced in API endpoints - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `added_at: number` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + The Unix timestamp (in seconds) of when the project was added. - The aggregated file search calls usage details of the specific time bucket. + - `object: "organization.project.user"` - - `num_requests: number` + The object type, which is always `organization.project.user` - The count of file search calls. + - `"organization.project.user"` - - `object: "organization.usage.file_searches.result"` + - `role: string` - - `"organization.usage.file_searches.result"` + `owner` or `member` - - `api_key_id: optional string` + - `email: optional string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The email address of the user - - `project_id: optional string` + - `name: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The name of the user - - `user_id: optional string` +- `has_more: boolean` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `object: string` - - `vector_store_id: optional string` +- `first_id: optional string` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +- `last_id: optional string` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +### Example - The aggregated web search calls usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `num_model_requests: number` +#### Response - The count of model requests. +```json +{ + "data": [ + { + "id": "id", + "added_at": 0, + "object": "organization.project.user", + "role": "role", + "email": "email", + "name": "name" + } + ], + "has_more": true, + "object": "object", + "first_id": "first_id", + "last_id": "last_id" +} +``` - - `num_requests: number` +### Example - The count of web search calls. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.web_searches.result"` +#### Response - - `"organization.usage.web_searches.result"` +```json +{ + "object": "list", + "data": [ + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "first_id": "user-abc", + "last_id": "user-xyz", + "has_more": false +} +``` - - `api_key_id: optional string` +## Retrieve project user - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +**get** `/organization/projects/{project_id}/users/{user_id}` - - `context_level: optional string` +Retrieves a user in the project. - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +### Path Parameters - - `model: optional string` +- `project_id: string` - When `group_by=model`, this field provides the model name of the grouped usage result. +- `user_id: string` - - `project_id: optional string` +### Returns - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `ProjectUser object { id, added_at, object, 3 more }` - - `user_id: optional string` + Represents an individual user in a project. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + The identifier, which can be referenced in API endpoints - The aggregated costs details of the specific time bucket. + - `added_at: number` - - `object: "organization.costs.result"` + The Unix timestamp (in seconds) of when the project was added. - - `"organization.costs.result"` + - `object: "organization.project.user"` - - `amount: optional object { currency, value }` + The object type, which is always `organization.project.user` - The monetary value in its associated currency. + - `"organization.project.user"` - - `currency: optional string` + - `role: string` - Lowercase ISO-4217 currency e.g. "usd" + `owner` or `member` - - `value: optional number` + - `email: optional string` - The numeric value of the cost. + The email address of the user - - `api_key_id: optional string` + - `name: optional string` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + The name of the user - - `line_item: optional string` +### Example - When `group_by=line_item`, this field provides the line item of the grouped costs result. +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `project_id: optional string` +#### Response - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +```json +{ + "id": "id", + "added_at": 0, + "object": "organization.project.user", + "role": "role", + "email": "email", + "name": "name" +} +``` - - `quantity: optional number` +### Example - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +```http +curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `start_time: number` +#### Response - - `has_more: boolean` +```json +{ + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 +} +``` - - `next_page: string` +## Modify project user - - `object: "page"` +**post** `/organization/projects/{project_id}/users/{user_id}` - - `"page"` +Modifies a user's role in the project. -### Usage Images Response +### Path Parameters -- `UsageImagesResponse object { data, has_more, next_page, object }` +- `project_id: string` - - `data: array of object { end_time, object, results, start_time }` +- `user_id: string` - - `end_time: number` +### Body Parameters - - `object: "bucket"` +- `role: optional string` - - `"bucket"` + `owner` or `member` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +### Returns - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +- `ProjectUser object { id, added_at, object, 3 more }` - The aggregated completions usage details of the specific time bucket. + Represents an individual user in a project. - - `input_tokens: number` + - `id: string` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The identifier, which can be referenced in API endpoints - - `num_model_requests: number` + - `added_at: number` - The count of requests made to the model. + The Unix timestamp (in seconds) of when the project was added. - - `object: "organization.usage.completions.result"` + - `object: "organization.project.user"` - - `"organization.usage.completions.result"` + The object type, which is always `organization.project.user` - - `output_tokens: number` + - `"organization.project.user"` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `role: string` - - `api_key_id: optional string` + `owner` or `member` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `email: optional string` - - `batch: optional boolean` + The email address of the user - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `name: optional string` - - `input_audio_tokens: optional number` + The name of the user - The aggregated number of uncached audio input tokens used. +### Example - - `input_cache_write_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - The aggregated number of input tokens written to the cache. +#### Response - - `input_cached_audio_tokens: optional number` +```json +{ + "id": "id", + "added_at": 0, + "object": "organization.project.user", + "role": "role", + "email": "email", + "name": "name" +} +``` - The aggregated number of cached audio input tokens used. +### Example - - `input_cached_image_tokens: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' +``` - The aggregated number of cached image input tokens used. +#### Response - - `input_cached_text_tokens: optional number` +```json +{ + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 +} +``` - The aggregated number of cached text input tokens used. +## Domain Types - - `input_cached_tokens: optional number` +### Project User - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +- `ProjectUser object { id, added_at, object, 3 more }` - - `input_image_tokens: optional number` + Represents an individual user in a project. - The aggregated number of uncached image input tokens used. + - `id: string` - - `input_text_tokens: optional number` + The identifier, which can be referenced in API endpoints - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + - `added_at: number` - - `input_uncached_tokens: optional number` + The Unix timestamp (in seconds) of when the project was added. - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + - `object: "organization.project.user"` - - `model: optional string` + The object type, which is always `organization.project.user` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"organization.project.user"` - - `output_audio_tokens: optional number` + - `role: string` - The aggregated number of audio output tokens used. + `owner` or `member` - - `output_image_tokens: optional number` + - `email: optional string` - The aggregated number of image output tokens used. + The email address of the user - - `output_text_tokens: optional number` + - `name: optional string` - The aggregated number of text output tokens used. + The name of the user - - `project_id: optional string` +### User Delete Response - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `UserDeleteResponse object { id, deleted, object }` - - `service_tier: optional string` + - `id: string` - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + - `deleted: boolean` - - `user_id: optional string` + - `object: "organization.project.user.deleted"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"organization.project.user.deleted"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +# Roles - The aggregated embeddings usage details of the specific time bucket. +## Assign project role to user - - `input_tokens: number` +**post** `/projects/{project_id}/users/{user_id}/roles` - The aggregated number of input tokens used. +Assigns a project role to a user within a project. - - `num_model_requests: number` +### Path Parameters - The count of requests made to the model. +- `project_id: string` - - `object: "organization.usage.embeddings.result"` +- `user_id: string` - - `"organization.usage.embeddings.result"` +### Body Parameters - - `api_key_id: optional string` +- `role_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Identifier of the role to assign. - - `model: optional string` +### Returns - When `group_by=model`, this field provides the model name of the grouped usage result. +- `object: "user.role"` - - `project_id: optional string` + Always `user.role`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"user.role"` - - `user_id: optional string` +- `role: Role` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Details about a role that can be assigned through the public Roles API. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `id: string` - The aggregated moderations usage details of the specific time bucket. + Identifier for the role. - - `input_tokens: number` + - `description: string` - The aggregated number of input tokens used. + Optional description of the role. - - `num_model_requests: number` + - `name: string` - The count of requests made to the model. + Unique name for the role. - - `object: "organization.usage.moderations.result"` + - `object: "role"` - - `"organization.usage.moderations.result"` + Always `role`. - - `api_key_id: optional string` + - `"role"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `permissions: array of string` - - `model: optional string` + Permissions granted by the role. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `predefined_role: boolean` - - `project_id: optional string` + Whether the role is predefined and managed by OpenAI. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `resource_type: string` - - `user_id: optional string` + Resource type the role is bound to (for example `api.organization` or `api.project`). - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `user: OrganizationUser` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + Represents an individual `user` within an organization. - The aggregated images usage details of the specific time bucket. + - `id: string` - - `images: number` + The identifier, which can be referenced in API endpoints - The number of images processed. + - `added_at: number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of when the user was added. - The count of requests made to the model. + - `object: "organization.user"` - - `object: "organization.usage.images.result"` + The object type, which is always `organization.user` - - `"organization.usage.images.result"` + - `"organization.user"` - - `api_key_id: optional string` + - `api_key_last_used_at: optional number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The Unix timestamp (in seconds) of the user's last API key usage. - - `model: optional string` + - `created: optional number` - When `group_by=model`, this field provides the model name of the grouped usage result. + The Unix timestamp (in seconds) of when the user was created. - - `project_id: optional string` + - `developer_persona: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The developer persona metadata for the user. - - `size: optional string` + - `email: optional string` - When `group_by=size`, this field provides the image size of the grouped usage result. + The email address of the user - - `source: optional string` + - `is_default: optional boolean` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + Whether this is the organization's default user. - - `user_id: optional string` + - `is_scale_tier_authorized_purchaser: optional boolean` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Whether the user is an authorized purchaser for Scale Tier. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `is_scim_managed: optional boolean` - The aggregated audio speeches usage details of the specific time bucket. + Whether the user is managed through SCIM. - - `characters: number` + - `is_service_account: optional boolean` - The number of characters processed. + Whether the user is a service account. - - `num_model_requests: number` + - `name: optional string` - The count of requests made to the model. + The name of the user - - `object: "organization.usage.audio_speeches.result"` + - `projects: optional object { data, object }` - - `"organization.usage.audio_speeches.result"` + Projects associated with the user, if included. - - `api_key_id: optional string` + - `data: array of object { id, name, role }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `id: optional string` - - `model: optional string` + - `name: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `role: optional string` - - `project_id: optional string` + - `object: "list"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"list"` - - `user_id: optional string` + - `role: optional string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + `owner` or `reader` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `technical_level: optional string` - The aggregated audio transcriptions usage details of the specific time bucket. + The technical level metadata for the user. - - `num_model_requests: number` + - `user: optional object { id, object, banned, 5 more }` - The count of requests made to the model. + Nested user details. - - `object: "organization.usage.audio_transcriptions.result"` + - `id: string` - - `"organization.usage.audio_transcriptions.result"` + - `object: "user"` - - `seconds: number` + - `"user"` - The number of seconds processed. + - `banned: optional boolean` - - `api_key_id: optional string` + - `banned_at: optional number` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `email: optional string` - - `model: optional string` + - `enabled: optional boolean` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `name: optional string` - - `project_id: optional string` + - `picture: optional string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Example - - `user_id: optional string` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "role_id": "role_id" + }' +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +#### Response - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +```json +{ + "object": "user.role", + "role": { + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" + }, + "user": { + "id": "id", + "added_at": 0, + "object": "organization.user", + "api_key_last_used_at": 0, + "created": 0, + "developer_persona": "developer_persona", + "email": "email", + "is_default": true, + "is_scale_tier_authorized_purchaser": true, + "is_scim_managed": true, + "is_service_account": true, + "name": "name", + "projects": { + "data": [ + { + "id": "id", + "name": "name", + "role": "role" + } + ], + "object": "list" + }, + "role": "role", + "technical_level": "technical_level", + "user": { + "id": "id", + "object": "user", + "banned": true, + "banned_at": 0, + "email": "email", + "enabled": true, + "name": "name", + "picture": "picture" + } + } +} +``` - The aggregated vector stores usage details of the specific time bucket. +### Example - - `object: "organization.usage.vector_stores.result"` +```http +curl -X POST https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_id": "role_01J1F8PROJ" + }' +``` - - `"organization.usage.vector_stores.result"` +#### Response - - `usage_bytes: number` +```json +{ + "object": "user.role", + "user": { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711470000 + }, + "role": { + "object": "role", + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "description": "Allows managing API keys for the project", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false + } +} +``` - The vector stores usage in bytes. +## Unassign project role from user - - `project_id: optional string` +**delete** `/projects/{project_id}/users/{user_id}/roles/{role_id}` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +Unassigns a project role from a user within a project. - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +### Path Parameters - The aggregated code interpreter sessions usage details of the specific time bucket. +- `project_id: string` - - `num_sessions: number` +- `user_id: string` - The number of code interpreter sessions. +- `role_id: string` - - `object: "organization.usage.code_interpreter_sessions.result"` +### Returns - - `"organization.usage.code_interpreter_sessions.result"` +- `deleted: boolean` - - `project_id: optional string` + Whether the assignment was removed. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `object: string` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. - The aggregated file search calls usage details of the specific time bucket. +### Example - - `num_requests: number` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles/$ROLE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The count of file search calls. +#### Response - - `object: "organization.usage.file_searches.result"` +```json +{ + "deleted": true, + "object": "object" +} +``` - - `"organization.usage.file_searches.result"` +### Example - - `api_key_id: optional string` +```http +curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `project_id: optional string` +```json +{ + "object": "user.role.deleted", + "deleted": true +} +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +## List project user role assignments - - `user_id: optional string` +**get** `/projects/{project_id}/users/{user_id}/roles` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +Lists the project roles assigned to a user within a project. - - `vector_store_id: optional string` +### Path Parameters - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +- `project_id: string` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` +- `user_id: string` - The aggregated web search calls usage details of the specific time bucket. +### Query Parameters - - `num_model_requests: number` +- `after: optional string` - The count of model requests. + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles. - - `num_requests: number` +- `limit: optional number` - The count of web search calls. + A limit on the number of project role assignments to return. - - `object: "organization.usage.web_searches.result"` +- `order: optional "asc" or "desc"` - - `"organization.usage.web_searches.result"` + Sort order for the returned project roles. - - `api_key_id: optional string` + - `"asc"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"desc"` - - `context_level: optional string` +### Returns - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +- `data: array of object { id, assignment_sources, created_at, 9 more }` - - `model: optional string` + Role assignments returned in the current page. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Identifier for the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `assignment_sources: array of object { principal_id, principal_type }` - - `user_id: optional string` + Principals from which the role assignment is inherited, when available. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `principal_id: string` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `principal_type: string` - The aggregated costs details of the specific time bucket. + - `created_at: number` - - `object: "organization.costs.result"` + When the role was created. - - `"organization.costs.result"` + - `created_by: string` - - `amount: optional object { currency, value }` + Identifier of the actor who created the role. - The monetary value in its associated currency. + - `created_by_user_obj: map[unknown]` - - `currency: optional string` + User details for the actor that created the role, when available. - Lowercase ISO-4217 currency e.g. "usd" + - `description: string` - - `value: optional number` + Description of the role. - The numeric value of the cost. + - `metadata: map[unknown]` - - `api_key_id: optional string` + Arbitrary metadata stored on the role. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `name: string` - - `line_item: optional string` + Name of the role. - When `group_by=line_item`, this field provides the line item of the grouped costs result. + - `permissions: array of string` - - `project_id: optional string` + Permissions associated with the role. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `predefined_role: boolean` - - `quantity: optional number` + Whether the role is predefined by OpenAI. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `resource_type: string` - - `start_time: number` + Resource type the role applies to. - - `has_more: boolean` + - `updated_at: number` - - `next_page: string` + When the role was last updated. - - `object: "page"` +- `has_more: boolean` - - `"page"` + Whether additional assignments are available when paginating. -### Usage Moderations Response +- `next: string` -- `UsageModerationsResponse object { data, has_more, next_page, object }` + Cursor to fetch the next page of results, or `null` when there are no more assignments. - - `data: array of object { end_time, object, results, start_time }` +- `object: "list"` - - `end_time: number` + Always `list`. - - `object: "bucket"` + - `"list"` - - `"bucket"` +### Example - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` +#### Response - The aggregated completions usage details of the specific time bucket. +```json +{ + "data": [ + { + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `input_tokens: number` +### Example - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```http +curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `num_model_requests: number` +#### Response - The count of requests made to the model. +```json +{ + "object": "list", + "data": [ + { + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null +} +``` - - `object: "organization.usage.completions.result"` +## Retrieve project user role - - `"organization.usage.completions.result"` +**get** `/projects/{project_id}/users/{user_id}/roles/{role_id}` - - `output_tokens: number` +Retrieves a project role assigned to a user. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +### Path Parameters - - `api_key_id: optional string` +- `project_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `user_id: string` - - `batch: optional boolean` +- `role_id: string` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +### Returns - - `input_audio_tokens: optional number` +- `id: string` - The aggregated number of uncached audio input tokens used. + Identifier for the role. - - `input_cache_write_tokens: optional number` +- `assignment_sources: array of object { principal_id, principal_type }` - The aggregated number of input tokens written to the cache. + Principals from which the role assignment is inherited, when available. - - `input_cached_audio_tokens: optional number` + - `principal_id: string` - The aggregated number of cached audio input tokens used. + - `principal_type: string` - - `input_cached_image_tokens: optional number` +- `created_at: number` - The aggregated number of cached image input tokens used. + When the role was created. - - `input_cached_text_tokens: optional number` +- `created_by: string` - The aggregated number of cached text input tokens used. + Identifier of the actor who created the role. - - `input_cached_tokens: optional number` +- `created_by_user_obj: map[unknown]` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + User details for the actor that created the role, when available. - - `input_image_tokens: optional number` +- `description: string` - The aggregated number of uncached image input tokens used. + Description of the role. - - `input_text_tokens: optional number` +- `metadata: map[unknown]` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. + Arbitrary metadata stored on the role. - - `input_uncached_tokens: optional number` +- `name: string` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + Name of the role. - - `model: optional string` +- `permissions: array of string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Permissions associated with the role. - - `output_audio_tokens: optional number` +- `predefined_role: boolean` - The aggregated number of audio output tokens used. + Whether the role is predefined by OpenAI. - - `output_image_tokens: optional number` +- `resource_type: string` - The aggregated number of image output tokens used. + Resource type the role applies to. - - `output_text_tokens: optional number` +- `updated_at: number` - The aggregated number of text output tokens used. + When the role was last updated. - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles/$ROLE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `service_tier: optional string` +#### Response - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +```json +{ + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 +} +``` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +#### Response - The aggregated embeddings usage details of the specific time bucket. +```json +{ + "id": "role_01J1F8PROJ", + "name": "API Project Key Manager", + "permissions": [ + "api.organization.projects.api_keys.read", + "api.organization.projects.api_keys.write" + ], + "resource_type": "api.project", + "predefined_role": false, + "description": "Allows managing API keys for the project", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": null, + "metadata": {}, + "assignment_sources": null +} +``` - - `input_tokens: number` +## Domain Types - The aggregated number of input tokens used. +### Role Create Response - - `num_model_requests: number` +- `RoleCreateResponse object { object, role, user }` - The count of requests made to the model. + Role assignment linking a user to a role. - - `object: "organization.usage.embeddings.result"` + - `object: "user.role"` - - `"organization.usage.embeddings.result"` + Always `user.role`. - - `api_key_id: optional string` + - `"user.role"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `role: Role` - - `model: optional string` + Details about a role that can be assigned through the public Roles API. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Identifier for the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `description: string` - - `user_id: optional string` + Optional description of the role. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `name: string` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + Unique name for the role. - The aggregated moderations usage details of the specific time bucket. + - `object: "role"` - - `input_tokens: number` + Always `role`. - The aggregated number of input tokens used. + - `"role"` - - `num_model_requests: number` + - `permissions: array of string` - The count of requests made to the model. + Permissions granted by the role. - - `object: "organization.usage.moderations.result"` + - `predefined_role: boolean` - - `"organization.usage.moderations.result"` + Whether the role is predefined and managed by OpenAI. - - `api_key_id: optional string` + - `resource_type: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `model: optional string` + - `user: OrganizationUser` - When `group_by=model`, this field provides the model name of the grouped usage result. + Represents an individual `user` within an organization. - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The identifier, which can be referenced in API endpoints - - `user_id: optional string` + - `added_at: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The Unix timestamp (in seconds) of when the user was added. - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + - `object: "organization.user"` - The aggregated images usage details of the specific time bucket. + The object type, which is always `organization.user` - - `images: number` + - `"organization.user"` - The number of images processed. + - `api_key_last_used_at: optional number` - - `num_model_requests: number` + The Unix timestamp (in seconds) of the user's last API key usage. - The count of requests made to the model. + - `created: optional number` - - `object: "organization.usage.images.result"` + The Unix timestamp (in seconds) of when the user was created. - - `"organization.usage.images.result"` + - `developer_persona: optional string` - - `api_key_id: optional string` + The developer persona metadata for the user. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `email: optional string` - - `model: optional string` + The email address of the user - When `group_by=model`, this field provides the model name of the grouped usage result. + - `is_default: optional boolean` - - `project_id: optional string` + Whether this is the organization's default user. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `is_scale_tier_authorized_purchaser: optional boolean` - - `size: optional string` + Whether the user is an authorized purchaser for Scale Tier. - When `group_by=size`, this field provides the image size of the grouped usage result. + - `is_scim_managed: optional boolean` - - `source: optional string` + Whether the user is managed through SCIM. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `is_service_account: optional boolean` - - `user_id: optional string` + Whether the user is a service account. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `name: optional string` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + The name of the user - The aggregated audio speeches usage details of the specific time bucket. + - `projects: optional object { data, object }` - - `characters: number` + Projects associated with the user, if included. - The number of characters processed. + - `data: array of object { id, name, role }` - - `num_model_requests: number` + - `id: optional string` - The count of requests made to the model. + - `name: optional string` - - `object: "organization.usage.audio_speeches.result"` + - `role: optional string` - - `"organization.usage.audio_speeches.result"` + - `object: "list"` - - `api_key_id: optional string` + - `"list"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `role: optional string` - - `model: optional string` + `owner` or `reader` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `technical_level: optional string` - - `project_id: optional string` + The technical level metadata for the user. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `user: optional object { id, object, banned, 5 more }` - - `user_id: optional string` + Nested user details. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `id: string` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `object: "user"` - The aggregated audio transcriptions usage details of the specific time bucket. + - `"user"` - - `num_model_requests: number` + - `banned: optional boolean` - The count of requests made to the model. + - `banned_at: optional number` - - `object: "organization.usage.audio_transcriptions.result"` + - `email: optional string` - - `"organization.usage.audio_transcriptions.result"` + - `enabled: optional boolean` - - `seconds: number` + - `name: optional string` - The number of seconds processed. + - `picture: optional string` - - `api_key_id: optional string` +### Role Delete Response - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `RoleDeleteResponse object { deleted, object }` - - `model: optional string` + Confirmation payload returned after unassigning a role. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `deleted: boolean` - - `project_id: optional string` + Whether the assignment was removed. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `object: string` - - `user_id: optional string` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Role List Response - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` - The aggregated vector stores usage details of the specific time bucket. + Detailed information about a role assignment entry returned when listing assignments. - - `object: "organization.usage.vector_stores.result"` + - `id: string` - - `"organization.usage.vector_stores.result"` + Identifier for the role. - - `usage_bytes: number` + - `assignment_sources: array of object { principal_id, principal_type }` - The vector stores usage in bytes. + Principals from which the role assignment is inherited, when available. - - `project_id: optional string` + - `principal_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `principal_type: string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + - `created_at: number` - The aggregated code interpreter sessions usage details of the specific time bucket. + When the role was created. - - `num_sessions: number` + - `created_by: string` - The number of code interpreter sessions. + Identifier of the actor who created the role. - - `object: "organization.usage.code_interpreter_sessions.result"` + - `created_by_user_obj: map[unknown]` - - `"organization.usage.code_interpreter_sessions.result"` + User details for the actor that created the role, when available. - - `project_id: optional string` + - `description: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Description of the role. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `metadata: map[unknown]` - The aggregated file search calls usage details of the specific time bucket. + Arbitrary metadata stored on the role. - - `num_requests: number` + - `name: string` - The count of file search calls. + Name of the role. - - `object: "organization.usage.file_searches.result"` + - `permissions: array of string` - - `"organization.usage.file_searches.result"` + Permissions associated with the role. - - `api_key_id: optional string` + - `predefined_role: boolean` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Whether the role is predefined by OpenAI. - - `project_id: optional string` + - `resource_type: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Resource type the role applies to. - - `user_id: optional string` + - `updated_at: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + When the role was last updated. - - `vector_store_id: optional string` +### Role Retrieve Response - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. +- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + Detailed information about a role assignment entry returned when listing assignments. - The aggregated web search calls usage details of the specific time bucket. + - `id: string` - - `num_model_requests: number` + Identifier for the role. - The count of model requests. + - `assignment_sources: array of object { principal_id, principal_type }` - - `num_requests: number` + Principals from which the role assignment is inherited, when available. - The count of web search calls. + - `principal_id: string` - - `object: "organization.usage.web_searches.result"` + - `principal_type: string` - - `"organization.usage.web_searches.result"` + - `created_at: number` - - `api_key_id: optional string` + When the role was created. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `created_by: string` - - `context_level: optional string` + Identifier of the actor who created the role. - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + - `created_by_user_obj: map[unknown]` - - `model: optional string` + User details for the actor that created the role, when available. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `description: string` - - `project_id: optional string` + Description of the role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `metadata: map[unknown]` - - `user_id: optional string` + Arbitrary metadata stored on the role. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `name: string` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + Name of the role. - The aggregated costs details of the specific time bucket. + - `permissions: array of string` - - `object: "organization.costs.result"` + Permissions associated with the role. - - `"organization.costs.result"` + - `predefined_role: boolean` - - `amount: optional object { currency, value }` + Whether the role is predefined by OpenAI. - The monetary value in its associated currency. + - `resource_type: string` - - `currency: optional string` + Resource type the role applies to. - Lowercase ISO-4217 currency e.g. "usd" + - `updated_at: number` - - `value: optional number` + When the role was last updated. - The numeric value of the cost. +# Roles - - `api_key_id: optional string` +## Create organization role - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. +**post** `/organization/roles` - - `line_item: optional string` +Creates a custom role for the organization. - When `group_by=line_item`, this field provides the line item of the grouped costs result. +### Body Parameters - - `project_id: optional string` +- `permissions: array of string` - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + Permissions to grant to the role. - - `quantity: optional number` +- `role_name: string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + Unique name for the role. - - `start_time: number` +- `description: optional string` - - `has_more: boolean` + Optional description of the role. - - `next_page: string` +### Returns - - `object: "page"` +- `Role object { id, description, name, 4 more }` - - `"page"` + Details about a role that can be assigned through the public Roles API. -### Usage Vector Stores Response + - `id: string` -- `UsageVectorStoresResponse object { data, has_more, next_page, object }` + Identifier for the role. - - `data: array of object { end_time, object, results, start_time }` + - `description: string` - - `end_time: number` + Optional description of the role. - - `object: "bucket"` + - `name: string` - - `"bucket"` + Unique name for the role. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `object: "role"` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + Always `role`. - The aggregated completions usage details of the specific time bucket. + - `"role"` - - `input_tokens: number` + - `permissions: array of string` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Permissions granted by the role. - - `num_model_requests: number` + - `predefined_role: boolean` - The count of requests made to the model. + Whether the role is predefined and managed by OpenAI. - - `object: "organization.usage.completions.result"` + - `resource_type: string` - - `"organization.usage.completions.result"` + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `output_tokens: number` +### Example - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +```http +curl https://api.openai.com/v1/organization/roles \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "permissions": [ + "string" + ], + "role_name": "role_name" + }' +``` - - `api_key_id: optional string` +#### Response - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - - `batch: optional boolean` +### Example - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. +```http +curl -X POST https://api.openai.com/v1/organization/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + }' +``` - - `input_audio_tokens: optional number` +#### Response - The aggregated number of uncached audio input tokens used. +```json +{ + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false +} +``` - - `input_cache_write_tokens: optional number` +## Delete organization role - The aggregated number of input tokens written to the cache. +**delete** `/organization/roles/{role_id}` - - `input_cached_audio_tokens: optional number` +Deletes a custom role from the organization. - The aggregated number of cached audio input tokens used. +### Path Parameters - - `input_cached_image_tokens: optional number` +- `role_id: string` - The aggregated number of cached image input tokens used. +### Returns - - `input_cached_text_tokens: optional number` +- `id: string` - The aggregated number of cached text input tokens used. + Identifier of the deleted role. - - `input_cached_tokens: optional number` +- `deleted: boolean` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + Whether the role was deleted. - - `input_image_tokens: optional number` +- `object: "role.deleted"` - The aggregated number of uncached image input tokens used. + Always `role.deleted`. - - `input_text_tokens: optional number` + - `"role.deleted"` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +### Example - - `input_uncached_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +#### Response - - `model: optional string` +```json +{ + "id": "id", + "deleted": true, + "object": "role.deleted" +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `output_audio_tokens: optional number` +```http +curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - The aggregated number of audio output tokens used. +#### Response - - `output_image_tokens: optional number` +```json +{ + "object": "role.deleted", + "id": "role_01J1F8ROLE01", + "deleted": true +} +``` - The aggregated number of image output tokens used. +## List organization roles - - `output_text_tokens: optional number` +**get** `/organization/roles` - The aggregated number of text output tokens used. +Lists the roles configured for the organization. - - `project_id: optional string` +### Query Parameters - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `after: optional string` - - `service_tier: optional string` + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles. - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +- `limit: optional number` - - `user_id: optional string` + A limit on the number of roles to return. Defaults to 1000. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +- `order: optional "asc" or "desc"` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + Sort order for the returned roles. - The aggregated embeddings usage details of the specific time bucket. + - `"asc"` - - `input_tokens: number` + - `"desc"` - The aggregated number of input tokens used. +### Returns - - `num_model_requests: number` +- `data: array of Role` - The count of requests made to the model. + Roles returned in the current page. - - `object: "organization.usage.embeddings.result"` + - `id: string` - - `"organization.usage.embeddings.result"` + Identifier for the role. - - `api_key_id: optional string` + - `description: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Optional description of the role. - - `model: optional string` + - `name: string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Unique name for the role. - - `project_id: optional string` + - `object: "role"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Always `role`. - - `user_id: optional string` + - `"role"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `permissions: array of string` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + Permissions granted by the role. - The aggregated moderations usage details of the specific time bucket. + - `predefined_role: boolean` - - `input_tokens: number` + Whether the role is predefined and managed by OpenAI. - The aggregated number of input tokens used. + - `resource_type: string` - - `num_model_requests: number` + Resource type the role is bound to (for example `api.organization` or `api.project`). - The count of requests made to the model. +- `has_more: boolean` - - `object: "organization.usage.moderations.result"` + Whether more roles are available when paginating. - - `"organization.usage.moderations.result"` +- `next: string` - - `api_key_id: optional string` + Cursor to fetch the next page of results, or `null` when there are no additional roles. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `object: "list"` - - `model: optional string` + Always `list`. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"list"` - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `user_id: optional string` +#### Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```json +{ + "data": [ + { + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +### Example - The aggregated images usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/roles?limit=20 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `images: number` +#### Response - The number of images processed. +```json +{ + "object": "list", + "data": [ + { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false + } + ], + "has_more": false, + "next": null +} +``` - - `num_model_requests: number` +## Retrieve organization role - The count of requests made to the model. +**get** `/organization/roles/{role_id}` - - `object: "organization.usage.images.result"` +Retrieves an organization role. - - `"organization.usage.images.result"` +### Path Parameters - - `api_key_id: optional string` +- `role_id: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +### Returns - - `model: optional string` +- `Role object { id, description, name, 4 more }` - When `group_by=model`, this field provides the model name of the grouped usage result. + Details about a role that can be assigned through the public Roles API. - - `project_id: optional string` + - `id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Identifier for the role. - - `size: optional string` + - `description: string` - When `group_by=size`, this field provides the image size of the grouped usage result. + Optional description of the role. - - `source: optional string` + - `name: string` - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + Unique name for the role. - - `user_id: optional string` + - `object: "role"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Always `role`. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` + - `"role"` - The aggregated audio speeches usage details of the specific time bucket. + - `permissions: array of string` - - `characters: number` + Permissions granted by the role. - The number of characters processed. + - `predefined_role: boolean` - - `num_model_requests: number` + Whether the role is predefined and managed by OpenAI. - The count of requests made to the model. + - `resource_type: string` - - `object: "organization.usage.audio_speeches.result"` + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `"organization.usage.audio_speeches.result"` +### Example - - `api_key_id: optional string` +```http +curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +#### Response - - `model: optional string` +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +## Update organization role - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` +**post** `/organization/roles/{role_id}` - The aggregated audio transcriptions usage details of the specific time bucket. +Updates an existing organization role. - - `num_model_requests: number` +### Path Parameters - The count of requests made to the model. +- `role_id: string` - - `object: "organization.usage.audio_transcriptions.result"` +### Body Parameters - - `"organization.usage.audio_transcriptions.result"` +- `description: optional string` - - `seconds: number` + New description for the role. - The number of seconds processed. +- `permissions: optional array of string` - - `api_key_id: optional string` + Updated set of permissions for the role. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `role_name: optional string` - - `model: optional string` + New name for the role. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Returns - - `project_id: optional string` +- `Role object { id, description, name, 4 more }` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Details about a role that can be assigned through the public Roles API. - - `user_id: optional string` + - `id: string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Identifier for the role. - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + - `description: string` - The aggregated vector stores usage details of the specific time bucket. + Optional description of the role. - - `object: "organization.usage.vector_stores.result"` + - `name: string` - - `"organization.usage.vector_stores.result"` + Unique name for the role. - - `usage_bytes: number` + - `object: "role"` - The vector stores usage in bytes. + Always `role`. - - `project_id: optional string` + - `"role"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `permissions: array of string` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + Permissions granted by the role. - The aggregated code interpreter sessions usage details of the specific time bucket. + - `predefined_role: boolean` - - `num_sessions: number` + Whether the role is predefined and managed by OpenAI. - The number of code interpreter sessions. + - `resource_type: string` - - `object: "organization.usage.code_interpreter_sessions.result"` + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `"organization.usage.code_interpreter_sessions.result"` +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +```json +{ + "id": "id", + "description": "description", + "name": "name", + "object": "role", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type" +} +``` - The aggregated file search calls usage details of the specific time bucket. +### Example - - `num_requests: number` +```http +curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role_name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "description": "Allows managing organization groups" + }' +``` - The count of file search calls. +#### Response - - `object: "organization.usage.file_searches.result"` +```json +{ + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false +} +``` - - `"organization.usage.file_searches.result"` +## Domain Types - - `api_key_id: optional string` +### Role - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `Role object { id, description, name, 4 more }` - - `project_id: optional string` + Details about a role that can be assigned through the public Roles API. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `id: string` - - `user_id: optional string` + Identifier for the role. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `description: string` - - `vector_store_id: optional string` + Optional description of the role. - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `name: string` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + Unique name for the role. - The aggregated web search calls usage details of the specific time bucket. + - `object: "role"` - - `num_model_requests: number` + Always `role`. - The count of model requests. + - `"role"` - - `num_requests: number` + - `permissions: array of string` - The count of web search calls. + Permissions granted by the role. - - `object: "organization.usage.web_searches.result"` + - `predefined_role: boolean` - - `"organization.usage.web_searches.result"` + Whether the role is predefined and managed by OpenAI. - - `api_key_id: optional string` + - `resource_type: string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `context_level: optional string` +### Role Delete Response - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +- `RoleDeleteResponse object { id, deleted, object }` - - `model: optional string` + Confirmation payload returned after deleting a role. - When `group_by=model`, this field provides the model name of the grouped usage result. + - `id: string` - - `project_id: optional string` + Identifier of the deleted role. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `deleted: boolean` - - `user_id: optional string` + Whether the role was deleted. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `object: "role.deleted"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + Always `role.deleted`. - The aggregated costs details of the specific time bucket. + - `"role.deleted"` - - `object: "organization.costs.result"` +# Spend Alerts - - `"organization.costs.result"` +## Create organization spend alert - - `amount: optional object { currency, value }` +**post** `/organization/spend_alerts` - The monetary value in its associated currency. +Creates an organization spend alert. - - `currency: optional string` +### Body Parameters - Lowercase ISO-4217 currency e.g. "usd" +- `currency: "USD"` - - `value: optional number` + The currency for the threshold amount. - The numeric value of the cost. + - `"USD"` - - `api_key_id: optional string` +- `interval: "month"` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + The time interval for evaluating spend against the threshold. - - `line_item: optional string` + - `"month"` - When `group_by=line_item`, this field provides the line item of the grouped costs result. +- `notification_channel: object { recipients, type, subject_prefix }` - - `project_id: optional string` + Email notification settings for a spend alert. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `recipients: array of string` - - `quantity: optional number` + Email addresses that receive the spend alert notification. - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + - `type: "email"` - - `start_time: number` + The notification channel type. Currently only `email` is supported. - - `has_more: boolean` + - `"email"` - - `next_page: string` + - `subject_prefix: optional string` - - `object: "page"` + Optional subject prefix for alert emails. - - `"page"` +- `threshold_amount: number` -### Usage File Search Calls Response + The alert threshold amount, in cents. -- `UsageFileSearchCallsResponse object { data, has_more, next_page, object }` +### Returns - - `data: array of object { end_time, object, results, start_time }` +- `OrganizationSpendAlert object { id, currency, interval, 3 more }` - - `end_time: number` + Represents a spend alert configured at the organization level. - - `object: "bucket"` + - `id: string` - - `"bucket"` + The identifier, which can be referenced in API endpoints. - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + - `currency: "USD"` - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + The currency for the threshold amount. - The aggregated completions usage details of the specific time bucket. + - `"USD"` - - `input_tokens: number` + - `interval: "month"` - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The time interval for evaluating spend against the threshold. - - `num_model_requests: number` + - `"month"` - The count of requests made to the model. + - `notification_channel: object { recipients, type, subject_prefix }` - - `object: "organization.usage.completions.result"` + Email notification settings for a spend alert. - - `"organization.usage.completions.result"` + - `recipients: array of string` - - `output_tokens: number` + Email addresses that receive the spend alert notification. - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `type: "email"` - - `api_key_id: optional string` + The notification channel type. Currently only `email` is supported. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"email"` - - `batch: optional boolean` + - `subject_prefix: optional string` - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + Optional subject prefix for alert emails. - - `input_audio_tokens: optional number` + - `object: "organization.spend_alert"` - The aggregated number of uncached audio input tokens used. + The object type, which is always `organization.spend_alert`. - - `input_cache_write_tokens: optional number` + - `"organization.spend_alert"` - The aggregated number of input tokens written to the cache. + - `threshold_amount: number` - - `input_cached_audio_tokens: optional number` + The alert threshold amount, in cents. - The aggregated number of cached audio input tokens used. +### Example - - `input_cached_image_tokens: optional number` +```http +curl https://api.openai.com/v1/organization/spend_alerts \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email" + }, + "threshold_amount": 0 + }' +``` - The aggregated number of cached image input tokens used. +#### Response - - `input_cached_text_tokens: optional number` +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "organization.spend_alert", + "threshold_amount": 0 +} +``` - The aggregated number of cached text input tokens used. +### Example - - `input_cached_tokens: optional number` +```http +curl -X POST https://api.openai.com/v1/organization/spend_alerts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + }' +``` - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. +#### Response - - `input_image_tokens: optional number` +```json +{ + "id": "alert_abc123", + "object": "organization.spend_alert", + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - The aggregated number of uncached image input tokens used. +## Delete organization spend alert - - `input_text_tokens: optional number` +**delete** `/organization/spend_alerts/{alert_id}` - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +Deletes an organization spend alert. - - `input_uncached_tokens: optional number` +### Path Parameters - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +- `alert_id: string` - - `model: optional string` +### Returns - When `group_by=model`, this field provides the model name of the grouped usage result. +- `OrganizationSpendAlertDeleted object { id, deleted, object }` - - `output_audio_tokens: optional number` + Confirmation payload returned after deleting an organization spend alert. - The aggregated number of audio output tokens used. + - `id: string` - - `output_image_tokens: optional number` + The deleted spend alert ID. - The aggregated number of image output tokens used. + - `deleted: boolean` - - `output_text_tokens: optional number` + Whether the spend alert was deleted. - The aggregated number of text output tokens used. + - `object: "organization.spend_alert.deleted"` - - `project_id: optional string` + Always `organization.spend_alert.deleted`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.spend_alert.deleted"` - - `service_tier: optional string` +### Example - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `user_id: optional string` +#### Response - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```json +{ + "id": "id", + "deleted": true, + "object": "organization.spend_alert.deleted" +} +``` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +### Example - The aggregated embeddings usage details of the specific time bucket. +```http +curl -X DELETE https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `input_tokens: number` +#### Response - The aggregated number of input tokens used. +```json +{ + "id": "alert_abc123", + "object": "organization.spend_alert.deleted", + "deleted": true +} +``` - - `num_model_requests: number` +## List organization spend alerts - The count of requests made to the model. +**get** `/organization/spend_alerts` - - `object: "organization.usage.embeddings.result"` +Lists organization spend alerts. - - `"organization.usage.embeddings.result"` +### Query Parameters - - `api_key_id: optional string` +- `after: optional string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page. - - `model: optional string` +- `before: optional string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page. - - `project_id: optional string` +- `limit: optional number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + A limit on the number of spend alerts to return. Defaults to 20. - - `user_id: optional string` +- `order: optional "asc" or "desc"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Sort order for the returned spend alerts. - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + - `"asc"` - The aggregated moderations usage details of the specific time bucket. + - `"desc"` - - `input_tokens: number` +### Returns - The aggregated number of input tokens used. +- `data: array of OrganizationSpendAlert` - - `num_model_requests: number` + Spend alerts returned in the current page. - The count of requests made to the model. + - `id: string` - - `object: "organization.usage.moderations.result"` + The identifier, which can be referenced in API endpoints. - - `"organization.usage.moderations.result"` + - `currency: "USD"` - - `api_key_id: optional string` + The currency for the threshold amount. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"USD"` - - `model: optional string` + - `interval: "month"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The time interval for evaluating spend against the threshold. - - `project_id: optional string` + - `"month"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `notification_channel: object { recipients, type, subject_prefix }` - - `user_id: optional string` + Email notification settings for a spend alert. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `recipients: array of string` - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` + Email addresses that receive the spend alert notification. - The aggregated images usage details of the specific time bucket. + - `type: "email"` - - `images: number` + The notification channel type. Currently only `email` is supported. - The number of images processed. + - `"email"` - - `num_model_requests: number` + - `subject_prefix: optional string` - The count of requests made to the model. + Optional subject prefix for alert emails. - - `object: "organization.usage.images.result"` + - `object: "organization.spend_alert"` - - `"organization.usage.images.result"` + The object type, which is always `organization.spend_alert`. - - `api_key_id: optional string` + - `"organization.spend_alert"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `threshold_amount: number` - - `model: optional string` + The alert threshold amount, in cents. - When `group_by=model`, this field provides the model name of the grouped usage result. +- `first_id: string` - - `project_id: optional string` + The ID of the first spend alert in this page. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +- `has_more: boolean` - - `size: optional string` + Whether more spend alerts are available when paginating. - When `group_by=size`, this field provides the image size of the grouped usage result. +- `last_id: string` - - `source: optional string` + The ID of the last spend alert in this page. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. +- `object: "list"` - - `user_id: optional string` + Always `list`. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"list"` - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +### Example - The aggregated audio speeches usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/spend_alerts \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `characters: number` +#### Response - The number of characters processed. +```json +{ + "data": [ + { + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "organization.spend_alert", + "threshold_amount": 0 + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/spend_alerts?limit=20&order=asc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.audio_speeches.result"` +#### Response - - `"organization.usage.audio_speeches.result"` +```json +{ + "object": "list", + "data": [ + { + "id": "alert_abc123", + "object": "organization.spend_alert", + "threshold_amount": 100000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + } + ], + "first_id": "alert_abc123", + "last_id": "alert_abc123", + "has_more": false +} +``` - - `api_key_id: optional string` +## Retrieve organization spend alert - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +**get** `/organization/spend_alerts/{alert_id}` - - `model: optional string` +Retrieves an organization spend alert. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Path Parameters - - `project_id: optional string` +- `alert_id: string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +### Returns - - `user_id: optional string` +- `OrganizationSpendAlert object { id, currency, interval, 3 more }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Represents a spend alert configured at the organization level. - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `id: string` - The aggregated audio transcriptions usage details of the specific time bucket. + The identifier, which can be referenced in API endpoints. - - `num_model_requests: number` + - `currency: "USD"` - The count of requests made to the model. + The currency for the threshold amount. - - `object: "organization.usage.audio_transcriptions.result"` + - `"USD"` - - `"organization.usage.audio_transcriptions.result"` + - `interval: "month"` - - `seconds: number` + The time interval for evaluating spend against the threshold. - The number of seconds processed. + - `"month"` - - `api_key_id: optional string` + - `notification_channel: object { recipients, type, subject_prefix }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Email notification settings for a spend alert. - - `model: optional string` + - `recipients: array of string` - When `group_by=model`, this field provides the model name of the grouped usage result. + Email addresses that receive the spend alert notification. - - `project_id: optional string` + - `type: "email"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The notification channel type. Currently only `email` is supported. - - `user_id: optional string` + - `"email"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `subject_prefix: optional string` - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` + Optional subject prefix for alert emails. - The aggregated vector stores usage details of the specific time bucket. + - `object: "organization.spend_alert"` - - `object: "organization.usage.vector_stores.result"` + The object type, which is always `organization.spend_alert`. - - `"organization.usage.vector_stores.result"` + - `"organization.spend_alert"` - - `usage_bytes: number` + - `threshold_amount: number` - The vector stores usage in bytes. + The alert threshold amount, in cents. - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` +#### Response - The aggregated code interpreter sessions usage details of the specific time bucket. +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "organization.spend_alert", + "threshold_amount": 0 +} +``` - - `num_sessions: number` +### Example - The number of code interpreter sessions. +```http +curl https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.code_interpreter_sessions.result"` +#### Response - - `"organization.usage.code_interpreter_sessions.result"` +```json +{ + "id": "alert_abc123", + "object": "organization.spend_alert", + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - - `project_id: optional string` +## Update organization spend alert - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +**post** `/organization/spend_alerts/{alert_id}` - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` +Updates an organization spend alert. - The aggregated file search calls usage details of the specific time bucket. +### Path Parameters - - `num_requests: number` +- `alert_id: string` - The count of file search calls. +### Body Parameters - - `object: "organization.usage.file_searches.result"` +- `currency: "USD"` - - `"organization.usage.file_searches.result"` + The currency for the threshold amount. - - `api_key_id: optional string` + - `"USD"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +- `interval: "month"` - - `project_id: optional string` + The time interval for evaluating spend against the threshold. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"month"` - - `user_id: optional string` +- `notification_channel: object { recipients, type, subject_prefix }` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Email notification settings for a spend alert. - - `vector_store_id: optional string` + - `recipients: array of string` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + Email addresses that receive the spend alert notification. - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + - `type: "email"` - The aggregated web search calls usage details of the specific time bucket. + The notification channel type. Currently only `email` is supported. - - `num_model_requests: number` + - `"email"` - The count of model requests. + - `subject_prefix: optional string` - - `num_requests: number` + Optional subject prefix for alert emails. - The count of web search calls. +- `threshold_amount: number` - - `object: "organization.usage.web_searches.result"` + The alert threshold amount, in cents. - - `"organization.usage.web_searches.result"` +### Returns - - `api_key_id: optional string` +- `OrganizationSpendAlert object { id, currency, interval, 3 more }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + Represents a spend alert configured at the organization level. - - `context_level: optional string` + - `id: string` - When `group_by=context_level`, this field provides the search context size of the grouped usage result. + The identifier, which can be referenced in API endpoints. - - `model: optional string` + - `currency: "USD"` - When `group_by=model`, this field provides the model name of the grouped usage result. + The currency for the threshold amount. - - `project_id: optional string` + - `"USD"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `interval: "month"` - - `user_id: optional string` + The time interval for evaluating spend against the threshold. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"month"` - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + - `notification_channel: object { recipients, type, subject_prefix }` - The aggregated costs details of the specific time bucket. + Email notification settings for a spend alert. - - `object: "organization.costs.result"` + - `recipients: array of string` - - `"organization.costs.result"` + Email addresses that receive the spend alert notification. - - `amount: optional object { currency, value }` + - `type: "email"` - The monetary value in its associated currency. + The notification channel type. Currently only `email` is supported. - - `currency: optional string` + - `"email"` - Lowercase ISO-4217 currency e.g. "usd" + - `subject_prefix: optional string` - - `value: optional number` + Optional subject prefix for alert emails. - The numeric value of the cost. + - `object: "organization.spend_alert"` - - `api_key_id: optional string` + The object type, which is always `organization.spend_alert`. - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `"organization.spend_alert"` - - `line_item: optional string` + - `threshold_amount: number` - When `group_by=line_item`, this field provides the line item of the grouped costs result. + The alert threshold amount, in cents. - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped costs result. +```http +curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email" + }, + "threshold_amount": 0 + }' +``` - - `quantity: optional number` +#### Response - When `group_by=line_item`, this field provides the quantity of the grouped costs result. +```json +{ + "id": "id", + "currency": "USD", + "interval": "month", + "notification_channel": { + "recipients": [ + "string" + ], + "type": "email", + "subject_prefix": "subject_prefix" + }, + "object": "organization.spend_alert", + "threshold_amount": 0 +} +``` - - `start_time: number` +### Example - - `has_more: boolean` +```http +curl -X POST https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } + }' +``` - - `next_page: string` +#### Response - - `object: "page"` +```json +{ + "id": "alert_abc123", + "object": "organization.spend_alert", + "threshold_amount": 150000, + "currency": "USD", + "interval": "month", + "notification_channel": { + "type": "email", + "recipients": ["finance@example.com"], + "subject_prefix": "OpenAI spend alert" + } +} +``` - - `"page"` +## Domain Types -### Usage Web Search Calls Response +### Organization Spend Alert -- `UsageWebSearchCallsResponse object { data, has_more, next_page, object }` +- `OrganizationSpendAlert object { id, currency, interval, 3 more }` - - `data: array of object { end_time, object, results, start_time }` + Represents a spend alert configured at the organization level. - - `end_time: number` + - `id: string` - - `object: "bucket"` + The identifier, which can be referenced in API endpoints. - - `"bucket"` + - `currency: "USD"` - - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` + The currency for the threshold amount. - - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` + - `"USD"` - The aggregated completions usage details of the specific time bucket. + - `interval: "month"` - - `input_tokens: number` + The time interval for evaluating spend against the threshold. - The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `"month"` - - `num_model_requests: number` + - `notification_channel: object { recipients, type, subject_prefix }` - The count of requests made to the model. + Email notification settings for a spend alert. - - `object: "organization.usage.completions.result"` + - `recipients: array of string` - - `"organization.usage.completions.result"` + Email addresses that receive the spend alert notification. - - `output_tokens: number` + - `type: "email"` - The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + The notification channel type. Currently only `email` is supported. - - `api_key_id: optional string` + - `"email"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `subject_prefix: optional string` - - `batch: optional boolean` + Optional subject prefix for alert emails. - When `group_by=batch`, this field tells whether the grouped usage result is batch or not. + - `object: "organization.spend_alert"` - - `input_audio_tokens: optional number` + The object type, which is always `organization.spend_alert`. - The aggregated number of uncached audio input tokens used. + - `"organization.spend_alert"` - - `input_cache_write_tokens: optional number` + - `threshold_amount: number` - The aggregated number of input tokens written to the cache. + The alert threshold amount, in cents. - - `input_cached_audio_tokens: optional number` +### Organization Spend Alert Deleted - The aggregated number of cached audio input tokens used. +- `OrganizationSpendAlertDeleted object { id, deleted, object }` - - `input_cached_image_tokens: optional number` + Confirmation payload returned after deleting an organization spend alert. - The aggregated number of cached image input tokens used. + - `id: string` - - `input_cached_text_tokens: optional number` + The deleted spend alert ID. - The aggregated number of cached text input tokens used. + - `deleted: boolean` - - `input_cached_tokens: optional number` + Whether the spend alert was deleted. - The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + - `object: "organization.spend_alert.deleted"` - - `input_image_tokens: optional number` + Always `organization.spend_alert.deleted`. - The aggregated number of uncached image input tokens used. + - `"organization.spend_alert.deleted"` - - `input_text_tokens: optional number` +# Spend Limit - The aggregated number of uncached text input tokens used, excluding cache-write tokens. +## Delete organization spend limit - - `input_uncached_tokens: optional number` +**delete** `/organization/spend_limit` - The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. +Delete the organization's hard spend limit. - - `model: optional string` +### Returns - When `group_by=model`, this field provides the model name of the grouped usage result. +- `OrganizationSpendLimitDeleted object { deleted, object }` - - `output_audio_tokens: optional number` + Confirmation payload returned after deleting an organization hard spend limit. - The aggregated number of audio output tokens used. + - `deleted: boolean` - - `output_image_tokens: optional number` + Whether the hard spend limit was deleted. - The aggregated number of image output tokens used. + - `object: "organization.spend_limit.deleted"` - - `output_text_tokens: optional number` + The object type, which is always `organization.spend_limit.deleted`. - The aggregated number of text output tokens used. + - `"organization.spend_limit.deleted"` - - `project_id: optional string` +### Example - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +```http +curl https://api.openai.com/v1/organization/spend_limit \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `service_tier: optional string` +#### Response - When `group_by=service_tier`, this field provides the service tier of the grouped usage result. +```json +{ + "deleted": true, + "object": "organization.spend_limit.deleted" +} +``` - - `user_id: optional string` +### Example - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +```http +curl -X DELETE https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` +#### Response - The aggregated embeddings usage details of the specific time bucket. +```json +{ + "object": "organization.spend_limit.deleted", + "deleted": true +} +``` - - `input_tokens: number` +## Retrieve organization spend limit - The aggregated number of input tokens used. +**get** `/organization/spend_limit` - - `num_model_requests: number` +Get the organization's hard spend limit. - The count of requests made to the model. +### Returns - - `object: "organization.usage.embeddings.result"` +- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` - - `"organization.usage.embeddings.result"` + Represents a hard spend limit configured at the organization level. - - `api_key_id: optional string` + - `currency: string or "USD"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The currency for the threshold amount. Currently, only `USD` is supported. - - `model: optional string` + - `string` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `"USD"` - - `project_id: optional string` + - `"USD"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `enforcement: object { status }` - - `user_id: optional string` + The current enforcement state of the hard spend limit. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `status: string or "inactive" or "enforcing"` - - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + Whether the hard spend limit is currently enforcing. - The aggregated moderations usage details of the specific time bucket. + - `string` - - `input_tokens: number` + - `"inactive" or "enforcing"` - The aggregated number of input tokens used. + Whether the hard spend limit is currently enforcing. - - `num_model_requests: number` + - `"inactive"` - The count of requests made to the model. + - `"enforcing"` - - `object: "organization.usage.moderations.result"` + - `interval: string or "month"` - - `"organization.usage.moderations.result"` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - - `api_key_id: optional string` + - `string` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `"month"` - - `model: optional string` + - `"month"` - When `group_by=model`, this field provides the model name of the grouped usage result. + - `object: "organization.spend_limit"` - - `project_id: optional string` + The object type, which is always `organization.spend_limit`. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"organization.spend_limit"` - - `user_id: optional string` + - `threshold_amount: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The hard spend limit amount, in cents. - - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` +### Example - The aggregated images usage details of the specific time bucket. +```http +curl https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `images: number` +#### Response - The number of images processed. +```json +{ + "currency": "USD", + "enforcement": { + "status": "inactive" + }, + "interval": "month", + "object": "organization.spend_limit", + "threshold_amount": 0 +} +``` - - `num_model_requests: number` +### Example - The count of requests made to the model. +```http +curl https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `object: "organization.usage.images.result"` +#### Response - - `"organization.usage.images.result"` +```json +{ + "object": "organization.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } +} +``` - - `api_key_id: optional string` +## Update organization spend limit - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +**post** `/organization/spend_limit` - - `model: optional string` +Create or replace the organization's hard spend limit. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Body Parameters - - `project_id: optional string` +- `currency: "USD"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + The currency for the threshold amount. Currently, only `USD` is supported. - - `size: optional string` + - `"USD"` - When `group_by=size`, this field provides the image size of the grouped usage result. +- `interval: "month"` - - `source: optional string` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. + - `"month"` - - `user_id: optional string` +- `threshold_amount: number` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The hard spend limit amount, in cents. - - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` +### Returns - The aggregated audio speeches usage details of the specific time bucket. +- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` - - `characters: number` + Represents a hard spend limit configured at the organization level. - The number of characters processed. + - `currency: string or "USD"` - - `num_model_requests: number` + The currency for the threshold amount. Currently, only `USD` is supported. - The count of requests made to the model. + - `string` - - `object: "organization.usage.audio_speeches.result"` + - `"USD"` - - `"organization.usage.audio_speeches.result"` + - `"USD"` - - `api_key_id: optional string` + - `enforcement: object { status }` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + The current enforcement state of the hard spend limit. - - `model: optional string` + - `status: string or "inactive" or "enforcing"` - When `group_by=model`, this field provides the model name of the grouped usage result. + Whether the hard spend limit is currently enforcing. - - `project_id: optional string` + - `string` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"inactive" or "enforcing"` - - `user_id: optional string` + Whether the hard spend limit is currently enforcing. - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + - `"inactive"` - - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` + - `"enforcing"` - The aggregated audio transcriptions usage details of the specific time bucket. + - `interval: string or "month"` - - `num_model_requests: number` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - The count of requests made to the model. + - `string` - - `object: "organization.usage.audio_transcriptions.result"` + - `"month"` - - `"organization.usage.audio_transcriptions.result"` + - `"month"` - - `seconds: number` + - `object: "organization.spend_limit"` - The number of seconds processed. + The object type, which is always `organization.spend_limit`. - - `api_key_id: optional string` + - `"organization.spend_limit"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `threshold_amount: number` - - `model: optional string` + The hard spend limit amount, in cents. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Example - - `project_id: optional string` +```http +curl https://api.openai.com/v1/organization/spend_limit \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{ + "currency": "USD", + "interval": "month", + "threshold_amount": 1 + }' +``` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. +#### Response - - `user_id: optional string` +```json +{ + "currency": "USD", + "enforcement": { + "status": "inactive" + }, + "interval": "month", + "object": "organization.spend_limit", + "threshold_amount": 0 +} +``` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. +### Example - - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` +```http +curl -X POST https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 10000, + "currency": "USD", + "interval": "month" + }' +``` - The aggregated vector stores usage details of the specific time bucket. +#### Response - - `object: "organization.usage.vector_stores.result"` +```json +{ + "object": "organization.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } +} +``` - - `"organization.usage.vector_stores.result"` +## Domain Types - - `usage_bytes: number` +### Organization Spend Limit - The vector stores usage in bytes. +- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` - - `project_id: optional string` + Represents a hard spend limit configured at the organization level. - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `currency: string or "USD"` - - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + The currency for the threshold amount. Currently, only `USD` is supported. - The aggregated code interpreter sessions usage details of the specific time bucket. + - `string` - - `num_sessions: number` + - `"USD"` - The number of code interpreter sessions. + - `"USD"` - - `object: "organization.usage.code_interpreter_sessions.result"` + - `enforcement: object { status }` - - `"organization.usage.code_interpreter_sessions.result"` + The current enforcement state of the hard spend limit. - - `project_id: optional string` + - `status: string or "inactive" or "enforcing"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Whether the hard spend limit is currently enforcing. - - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` + - `string` - The aggregated file search calls usage details of the specific time bucket. + - `"inactive" or "enforcing"` - - `num_requests: number` + Whether the hard spend limit is currently enforcing. - The count of file search calls. + - `"inactive"` - - `object: "organization.usage.file_searches.result"` + - `"enforcing"` - - `"organization.usage.file_searches.result"` + - `interval: string or "month"` - - `api_key_id: optional string` + The time interval for evaluating spend against the threshold. Currently, only `month` is supported. - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + - `string` - - `project_id: optional string` + - `"month"` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + - `"month"` - - `user_id: optional string` + - `object: "organization.spend_limit"` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + The object type, which is always `organization.spend_limit`. - - `vector_store_id: optional string` + - `"organization.spend_limit"` - When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + - `threshold_amount: number` - - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + The hard spend limit amount, in cents. - The aggregated web search calls usage details of the specific time bucket. +### Organization Spend Limit Deleted - - `num_model_requests: number` +- `OrganizationSpendLimitDeleted object { deleted, object }` - The count of model requests. + Confirmation payload returned after deleting an organization hard spend limit. - - `num_requests: number` + - `deleted: boolean` - The count of web search calls. + Whether the hard spend limit was deleted. - - `object: "organization.usage.web_searches.result"` + - `object: "organization.spend_limit.deleted"` - - `"organization.usage.web_searches.result"` + The object type, which is always `organization.spend_limit.deleted`. - - `api_key_id: optional string` + - `"organization.spend_limit.deleted"` - When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. +# Usage - - `context_level: optional string` +## Audio speeches - When `group_by=context_level`, this field provides the search context size of the grouped usage result. +**get** `/organization/usage/audio_speeches` - - `model: optional string` +Get audio speeches usage details for the organization. - When `group_by=model`, this field provides the model name of the grouped usage result. +### Query Parameters - - `project_id: optional string` +- `start_time: number` - When `group_by=project_id`, this field provides the project ID of the grouped usage result. + Start time (Unix seconds) of the query time range, inclusive. - - `user_id: optional string` +- `api_key_ids: optional array of string` - When `group_by=user_id`, this field provides the user ID of the grouped usage result. + Return only usage for these API keys. - - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` +- `bucket_width: optional "1m" or "1h" or "1d"` - The aggregated costs details of the specific time bucket. + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - `object: "organization.costs.result"` + - `"1m"` - - `"organization.costs.result"` + - `"1h"` - - `amount: optional object { currency, value }` + - `"1d"` - The monetary value in its associated currency. +- `end_time: optional number` - - `currency: optional string` + End time (Unix seconds) of the query time range, exclusive. - Lowercase ISO-4217 currency e.g. "usd" +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` - - `value: optional number` + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. - The numeric value of the cost. + - `"project_id"` - - `api_key_id: optional string` + - `"user_id"` - When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. + - `"api_key_id"` - - `line_item: optional string` + - `"model"` - When `group_by=line_item`, this field provides the line item of the grouped costs result. +- `limit: optional number` - - `project_id: optional string` + Specifies the number of buckets to return. - When `group_by=project_id`, this field provides the project ID of the grouped costs result. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - - `quantity: optional number` +- `models: optional array of string` - When `group_by=line_item`, this field provides the quantity of the grouped costs result. + Return only usage for these models. - - `start_time: number` +- `page: optional string` - - `has_more: boolean` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - - `next_page: string` +- `project_ids: optional array of string` - - `object: "page"` + Return only usage for these projects. - - `"page"` +- `user_ids: optional array of string` -### Usage Costs Response + Return only usage for these users. -- `UsageCostsResponse object { data, has_more, next_page, object }` +### Returns - - `data: array of object { end_time, object, results, start_time }` +- `data: array of object { end_time, object, results, start_time }` - `end_time: number` @@ -14688,118 +17280,18 @@ curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1 - `start_time: number` - - `has_more: boolean` - - - `next_page: string` - - - `object: "page"` - - - `"page"` - -# Invites - -## List invites - -**get** `/organization/invites` - -Returns a list of invites in the organization. - -### Query Parameters - -- `after: optional string` - - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - -- `limit: optional number` - - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - -### Returns - -- `data: array of Invite` - - - `id: string` - - The identifier, which can be referenced in API endpoints - - - `created_at: number` - - The Unix timestamp (in seconds) of when the invite was sent. - - - `email: string` - - The email address of the individual to whom the invite was sent - - - `object: "organization.invite"` - - The object type, which is always `organization.invite` - - - `"organization.invite"` - - - `projects: array of object { id, role }` - - The projects that were granted membership upon acceptance of the invite. - - - `id: string` - - Project's public ID - - - `role: "member" or "owner"` - - Project membership role - - - `"member"` - - - `"owner"` - - - `role: "owner" or "reader"` - - `owner` or `reader` - - - `"owner"` - - - `"reader"` - - - `status: "accepted" or "expired" or "pending"` - - `accepted`,`expired`, or `pending` - - - `"accepted"` - - - `"expired"` - - - `"pending"` - - - `accepted_at: optional number` - - The Unix timestamp (in seconds) of when the invite was accepted. - - - `expires_at: optional number` - - The Unix timestamp (in seconds) of when the invite expires. - - `has_more: boolean` - The `has_more` property is used for pagination to indicate there are additional results. - -- `object: "list"` - - The object type, which is always `list` - - - `"list"` - -- `first_id: optional string` - - The first `invite_id` in the retrieved `list` +- `next_page: string` -- `last_id: optional string` +- `object: "page"` - The last `invite_id` in the retrieved `list` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/invites \ +curl https://api.openai.com/v1/organization/usage/audio_speeches \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -14809,645 +17301,563 @@ curl https://api.openai.com/v1/organization/invites \ { "data": [ { - "id": "id", - "created_at": 0, - "email": "email", - "object": "organization.invite", - "projects": [ + "end_time": 0, + "object": "bucket", + "results": [ { - "id": "id", - "role": "member" + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" } ], - "role": "owner", - "status": "accepted", - "accepted_at": 0, - "expires_at": 0 + "start_time": 0 } ], "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "list", + "object": "page", "data": [ { - "object": "organization.invite", - "id": "invite-abc", - "email": "user@example.com", - "role": "owner", - "status": "accepted", - "created_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": 1711471533 + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.audio_speeches.result", + "characters": 45, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] } ], - "first_id": "invite-abc", - "last_id": "invite-abc", - "has_more": false + "has_more": false, + "next_page": null } ``` -## Create invite +## Audio transcriptions -**post** `/organization/invites` +**get** `/organization/usage/audio_transcriptions` -Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization. +Get audio transcriptions usage details for the organization. -### Body Parameters +### Query Parameters -- `email: string` +- `start_time: number` - Send an email to this address + Start time (Unix seconds) of the query time range, inclusive. -- `role: "reader" or "owner"` +- `api_key_ids: optional array of string` - `owner` or `reader` + Return only usage for these API keys. - - `"reader"` +- `bucket_width: optional "1m" or "1h" or "1d"` - - `"owner"` + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. -- `projects: optional array of object { id, role }` + - `"1m"` - An array of projects to which membership is granted at the same time the org invite is accepted. If omitted, the user will be invited to the default project for compatibility with legacy behavior. If empty list is passed, the user will not be invited to any projects, including the default one. + - `"1h"` - - `id: string` + - `"1d"` - Project's public ID +- `end_time: optional number` - - `role: "member" or "owner"` + End time (Unix seconds) of the query time range, exclusive. - Project membership role +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` - - `"member"` + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. - - `"owner"` + - `"project_id"` -### Returns + - `"user_id"` -- `Invite object { id, created_at, email, 6 more }` + - `"api_key_id"` - Represents an individual `invite` to the organization. + - `"model"` - - `id: string` +- `limit: optional number` - The identifier, which can be referenced in API endpoints + Specifies the number of buckets to return. - - `created_at: number` + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - The Unix timestamp (in seconds) of when the invite was sent. +- `models: optional array of string` - - `email: string` + Return only usage for these models. - The email address of the individual to whom the invite was sent +- `page: optional string` - - `object: "organization.invite"` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - The object type, which is always `organization.invite` +- `project_ids: optional array of string` - - `"organization.invite"` + Return only usage for these projects. - - `projects: array of object { id, role }` +- `user_ids: optional array of string` - The projects that were granted membership upon acceptance of the invite. + Return only usage for these users. - - `id: string` +### Returns - Project's public ID +- `data: array of object { end_time, object, results, start_time }` - - `role: "member" or "owner"` + - `end_time: number` - Project membership role + - `object: "bucket"` - - `"member"` + - `"bucket"` - - `"owner"` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `role: "owner" or "reader"` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - `owner` or `reader` + The aggregated completions usage details of the specific time bucket. - - `"owner"` + - `input_tokens: number` - - `"reader"` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `status: "accepted" or "expired" or "pending"` + - `num_model_requests: number` - `accepted`,`expired`, or `pending` + The count of requests made to the model. - - `"accepted"` + - `object: "organization.usage.completions.result"` - - `"expired"` + - `"organization.usage.completions.result"` - - `"pending"` + - `output_tokens: number` - - `accepted_at: optional number` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The Unix timestamp (in seconds) of when the invite was accepted. + - `api_key_id: optional string` - - `expires_at: optional number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The Unix timestamp (in seconds) of when the invite expires. + - `batch: optional boolean` -### Example + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -```http -curl https://api.openai.com/v1/organization/invites \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "email": "email", - "role": "reader" - }' -``` + - `input_audio_tokens: optional number` -#### Response + The aggregated number of uncached audio input tokens used. -```json -{ - "id": "id", - "created_at": 0, - "email": "email", - "object": "organization.invite", - "projects": [ - { - "id": "id", - "role": "member" - } - ], - "role": "owner", - "status": "accepted", - "accepted_at": 0, - "expires_at": 0 -} -``` + - `input_cache_write_tokens: optional number` -### Example + The aggregated number of input tokens written to the cache. -```http -curl -X POST https://api.openai.com/v1/organization/invites \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "email": "anotheruser@example.com", - "role": "reader", - "projects": [ - { - "id": "project-xyz", - "role": "member" - }, - { - "id": "project-abc", - "role": "owner" - } - ] - }' -``` + - `input_cached_audio_tokens: optional number` -#### Response + The aggregated number of cached audio input tokens used. -```json -{ - "object": "organization.invite", - "id": "invite-def", - "email": "anotheruser@example.com", - "role": "reader", - "status": "pending", - "created_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": null, - "projects": [ - { - "id": "project-xyz", - "role": "member" - }, - { - "id": "project-abc", - "role": "owner" - } - ] -} -``` + - `input_cached_image_tokens: optional number` -## Retrieve invite + The aggregated number of cached image input tokens used. -**get** `/organization/invites/{invite_id}` + - `input_cached_text_tokens: optional number` -Retrieves an invite. + The aggregated number of cached text input tokens used. -### Path Parameters + - `input_cached_tokens: optional number` -- `invite_id: string` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Returns + - `input_image_tokens: optional number` -- `Invite object { id, created_at, email, 6 more }` + The aggregated number of uncached image input tokens used. - Represents an individual `invite` to the organization. + - `input_text_tokens: optional number` - - `id: string` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - The identifier, which can be referenced in API endpoints + - `input_uncached_tokens: optional number` - - `created_at: number` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - The Unix timestamp (in seconds) of when the invite was sent. + - `model: optional string` + + When `group_by=model`, this field provides the model name of the grouped usage result. + + - `output_audio_tokens: optional number` + + The aggregated number of audio output tokens used. + + - `output_image_tokens: optional number` + + The aggregated number of image output tokens used. + + - `output_text_tokens: optional number` + + The aggregated number of text output tokens used. + + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `email: string` + - `service_tier: optional string` - The email address of the individual to whom the invite was sent + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `object: "organization.invite"` + - `user_id: optional string` - The object type, which is always `organization.invite` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"organization.invite"` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - - `projects: array of object { id, role }` + The aggregated embeddings usage details of the specific time bucket. - The projects that were granted membership upon acceptance of the invite. + - `input_tokens: number` - - `id: string` + The aggregated number of input tokens used. - Project's public ID + - `num_model_requests: number` - - `role: "member" or "owner"` + The count of requests made to the model. - Project membership role + - `object: "organization.usage.embeddings.result"` - - `"member"` + - `"organization.usage.embeddings.result"` - - `"owner"` + - `api_key_id: optional string` - - `role: "owner" or "reader"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - `owner` or `reader` + - `model: optional string` - - `"owner"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"reader"` + - `project_id: optional string` - - `status: "accepted" or "expired" or "pending"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - `accepted`,`expired`, or `pending` + - `user_id: optional string` - - `"accepted"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"expired"` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `"pending"` + The aggregated moderations usage details of the specific time bucket. - - `accepted_at: optional number` + - `input_tokens: number` - The Unix timestamp (in seconds) of when the invite was accepted. + The aggregated number of input tokens used. - - `expires_at: optional number` + - `num_model_requests: number` - The Unix timestamp (in seconds) of when the invite expires. + The count of requests made to the model. -### Example + - `object: "organization.usage.moderations.result"` -```http -curl https://api.openai.com/v1/organization/invites/$INVITE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.usage.moderations.result"` -#### Response + - `api_key_id: optional string` -```json -{ - "id": "id", - "created_at": 0, - "email": "email", - "object": "organization.invite", - "projects": [ - { - "id": "id", - "role": "member" - } - ], - "role": "owner", - "status": "accepted", - "accepted_at": 0, - "expires_at": 0 -} -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Example + - `model: optional string` -```http -curl https://api.openai.com/v1/organization/invites/invite-abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -#### Response + - `project_id: optional string` -```json -{ - "object": "organization.invite", - "id": "invite-abc", - "email": "user@example.com", - "role": "owner", - "status": "accepted", - "created_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": 1711471533 -} -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -## Delete invite + - `user_id: optional string` -**delete** `/organization/invites/{invite_id}` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -Delete an invite. If the invite has already been accepted, it cannot be deleted. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -### Path Parameters + The aggregated images usage details of the specific time bucket. -- `invite_id: string` + - `images: number` -### Returns + The number of images processed. -- `id: string` + - `num_model_requests: number` -- `deleted: boolean` + The count of requests made to the model. -- `object: "organization.invite.deleted"` + - `object: "organization.usage.images.result"` - The object type, which is always `organization.invite.deleted` + - `"organization.usage.images.result"` - - `"organization.invite.deleted"` + - `api_key_id: optional string` -### Example + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/invites/$INVITE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `model: optional string` -#### Response + When `group_by=model`, this field provides the model name of the grouped usage result. -```json -{ - "id": "id", - "deleted": true, - "object": "organization.invite.deleted" -} -``` + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `size: optional string` -#### Response + When `group_by=size`, this field provides the image size of the grouped usage result. -```json -{ - "object": "organization.invite.deleted", - "id": "invite-abc", - "deleted": true -} -``` + - `source: optional string` -## Domain Types + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -### Invite + - `user_id: optional string` -- `Invite object { id, created_at, email, 6 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Represents an individual `invite` to the organization. + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `id: string` + The aggregated audio speeches usage details of the specific time bucket. - The identifier, which can be referenced in API endpoints + - `characters: number` - - `created_at: number` + The number of characters processed. - The Unix timestamp (in seconds) of when the invite was sent. + - `num_model_requests: number` - - `email: string` + The count of requests made to the model. - The email address of the individual to whom the invite was sent + - `object: "organization.usage.audio_speeches.result"` - - `object: "organization.invite"` + - `"organization.usage.audio_speeches.result"` - The object type, which is always `organization.invite` + - `api_key_id: optional string` - - `"organization.invite"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `projects: array of object { id, role }` + - `model: optional string` - The projects that were granted membership upon acceptance of the invite. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `id: string` + - `project_id: optional string` - Project's public ID + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `role: "member" or "owner"` + - `user_id: optional string` - Project membership role + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"member"` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `"owner"` + The aggregated audio transcriptions usage details of the specific time bucket. - - `role: "owner" or "reader"` + - `num_model_requests: number` - `owner` or `reader` + The count of requests made to the model. - - `"owner"` + - `object: "organization.usage.audio_transcriptions.result"` - - `"reader"` + - `"organization.usage.audio_transcriptions.result"` - - `status: "accepted" or "expired" or "pending"` + - `seconds: number` - `accepted`,`expired`, or `pending` + The number of seconds processed. - - `"accepted"` + - `api_key_id: optional string` - - `"expired"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"pending"` + - `model: optional string` - - `accepted_at: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - The Unix timestamp (in seconds) of when the invite was accepted. + - `project_id: optional string` - - `expires_at: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the invite expires. + - `user_id: optional string` -### Invite Delete Response + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `InviteDeleteResponse object { id, deleted, object }` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `id: string` + The aggregated vector stores usage details of the specific time bucket. - - `deleted: boolean` + - `object: "organization.usage.vector_stores.result"` - - `object: "organization.invite.deleted"` + - `"organization.usage.vector_stores.result"` - The object type, which is always `organization.invite.deleted` + - `usage_bytes: number` - - `"organization.invite.deleted"` + The vector stores usage in bytes. -# Users + - `project_id: optional string` -## List users + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -**get** `/organization/users` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -Lists all of the users in the organization. + The aggregated code interpreter sessions usage details of the specific time bucket. -### Query Parameters + - `num_sessions: number` -- `after: optional string` + The number of code interpreter sessions. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `object: "organization.usage.code_interpreter_sessions.result"` -- `emails: optional array of string` + - `"organization.usage.code_interpreter_sessions.result"` - Filter by the email address of users. + - `project_id: optional string` -- `limit: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -### Returns + The aggregated file search calls usage details of the specific time bucket. -- `data: array of OrganizationUser` + - `num_requests: number` - - `id: string` + The count of file search calls. - The identifier, which can be referenced in API endpoints + - `object: "organization.usage.file_searches.result"` - - `added_at: number` + - `"organization.usage.file_searches.result"` - The Unix timestamp (in seconds) of when the user was added. + - `api_key_id: optional string` - - `object: "organization.user"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The object type, which is always `organization.user` + - `project_id: optional string` - - `"organization.user"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `api_key_last_used_at: optional number` + - `user_id: optional string` - The Unix timestamp (in seconds) of the user's last API key usage. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `created: optional number` + - `vector_store_id: optional string` - The Unix timestamp (in seconds) of when the user was created. + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - - `developer_persona: optional string` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - The developer persona metadata for the user. + The aggregated web search calls usage details of the specific time bucket. - - `email: optional string` + - `num_model_requests: number` - The email address of the user + The count of model requests. - - `is_default: optional boolean` + - `num_requests: number` - Whether this is the organization's default user. + The count of web search calls. - - `is_scale_tier_authorized_purchaser: optional boolean` + - `object: "organization.usage.web_searches.result"` - Whether the user is an authorized purchaser for Scale Tier. + - `"organization.usage.web_searches.result"` - - `is_scim_managed: optional boolean` + - `api_key_id: optional string` - Whether the user is managed through SCIM. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `is_service_account: optional boolean` + - `context_level: optional string` - Whether the user is a service account. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `name: optional string` + - `model: optional string` - The name of the user + When `group_by=model`, this field provides the model name of the grouped usage result. - - `projects: optional object { data, object }` + - `project_id: optional string` - Projects associated with the user, if included. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `data: array of object { id, name, role }` + - `user_id: optional string` - - `id: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `name: optional string` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `role: optional string` + The aggregated costs details of the specific time bucket. - - `object: "list"` + - `object: "organization.costs.result"` - - `"list"` + - `"organization.costs.result"` - - `role: optional string` + - `amount: optional object { currency, value }` - `owner` or `reader` + The monetary value in its associated currency. - - `technical_level: optional string` + - `currency: optional string` - The technical level metadata for the user. + Lowercase ISO-4217 currency e.g. "usd" - - `user: optional object { id, object, banned, 5 more }` + - `value: optional number` - Nested user details. + The numeric value of the cost. - - `id: string` + - `api_key_id: optional string` - - `object: "user"` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `"user"` + - `line_item: optional string` - - `banned: optional boolean` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `banned_at: optional number` + - `project_id: optional string` - - `email: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `enabled: optional boolean` + - `quantity: optional number` - - `name: optional string` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `picture: optional string` + - `start_time: number` - `has_more: boolean` -- `object: "list"` - - - `"list"` +- `next_page: string` -- `first_id: optional string` +- `object: "page"` -- `last_id: optional string` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/users \ +curl https://api.openai.com/v1/organization/usage/audio_transcriptions \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -15457,1950 +17867,1678 @@ curl https://api.openai.com/v1/organization/users \ { "data": [ { - "id": "id", - "added_at": 0, - "object": "organization.user", - "api_key_last_used_at": 0, - "created": 0, - "developer_persona": "developer_persona", - "email": "email", - "is_default": true, - "is_scale_tier_authorized_purchaser": true, - "is_scim_managed": true, - "is_service_account": true, - "name": "name", - "projects": { - "data": [ + "end_time": 0, + "object": "bucket", + "results": [ { - "id": "id", - "name": "name", - "role": "role" + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" } ], - "object": "list" - }, - "role": "role", - "technical_level": "technical_level", - "user": { - "id": "id", - "object": "user", - "banned": true, - "banned_at": 0, - "email": "email", - "enabled": true, - "name": "name", - "picture": "picture" - } + "start_time": 0 } ], "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "list", + "object": "page", "data": [ { - "object": "organization.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.audio_transcriptions.result", + "seconds": 20, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] } ], - "first_id": "user-abc", - "last_id": "user-xyz", - "has_more": false + "has_more": false, + "next_page": null } ``` -## Retrieve user +## Code interpreter sessions -**get** `/organization/users/{user_id}` +**get** `/organization/usage/code_interpreter_sessions` -Retrieves a user by their identifier. +Get code interpreter sessions usage details for the organization. -### Path Parameters +### Query Parameters -- `user_id: string` +- `start_time: number` -### Returns + Start time (Unix seconds) of the query time range, inclusive. + +- `bucket_width: optional "1m" or "1h" or "1d"` + + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. + + - `"1m"` + + - `"1h"` + + - `"1d"` + +- `end_time: optional number` + + End time (Unix seconds) of the query time range, exclusive. + +- `group_by: optional array of "project_id"` + + Group the usage data by the specified fields. Support fields include `project_id`. + + - `"project_id"` + +- `limit: optional number` + + Specifies the number of buckets to return. + + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + +- `page: optional string` -- `OrganizationUser object { id, added_at, object, 13 more }` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - Represents an individual `user` within an organization. +- `project_ids: optional array of string` - - `id: string` + Return only usage for these projects. - The identifier, which can be referenced in API endpoints +### Returns - - `added_at: number` +- `data: array of object { end_time, object, results, start_time }` - The Unix timestamp (in seconds) of when the user was added. + - `end_time: number` - - `object: "organization.user"` + - `object: "bucket"` - The object type, which is always `organization.user` + - `"bucket"` - - `"organization.user"` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `api_key_last_used_at: optional number` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - The Unix timestamp (in seconds) of the user's last API key usage. + The aggregated completions usage details of the specific time bucket. - - `created: optional number` + - `input_tokens: number` - The Unix timestamp (in seconds) of when the user was created. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `developer_persona: optional string` + - `num_model_requests: number` - The developer persona metadata for the user. + The count of requests made to the model. - - `email: optional string` + - `object: "organization.usage.completions.result"` - The email address of the user + - `"organization.usage.completions.result"` - - `is_default: optional boolean` + - `output_tokens: number` - Whether this is the organization's default user. + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `is_scale_tier_authorized_purchaser: optional boolean` + - `api_key_id: optional string` - Whether the user is an authorized purchaser for Scale Tier. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `is_scim_managed: optional boolean` + - `batch: optional boolean` - Whether the user is managed through SCIM. + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - - `is_service_account: optional boolean` + - `input_audio_tokens: optional number` - Whether the user is a service account. + The aggregated number of uncached audio input tokens used. - - `name: optional string` + - `input_cache_write_tokens: optional number` - The name of the user + The aggregated number of input tokens written to the cache. - - `projects: optional object { data, object }` + - `input_cached_audio_tokens: optional number` - Projects associated with the user, if included. + The aggregated number of cached audio input tokens used. - - `data: array of object { id, name, role }` + - `input_cached_image_tokens: optional number` - - `id: optional string` + The aggregated number of cached image input tokens used. - - `name: optional string` + - `input_cached_text_tokens: optional number` - - `role: optional string` + The aggregated number of cached text input tokens used. - - `object: "list"` + - `input_cached_tokens: optional number` - - `"list"` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `role: optional string` + - `input_image_tokens: optional number` - `owner` or `reader` + The aggregated number of uncached image input tokens used. - - `technical_level: optional string` + - `input_text_tokens: optional number` - The technical level metadata for the user. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `user: optional object { id, object, banned, 5 more }` + - `input_uncached_tokens: optional number` - Nested user details. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `id: string` + - `model: optional string` - - `object: "user"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"user"` + - `output_audio_tokens: optional number` - - `banned: optional boolean` + The aggregated number of audio output tokens used. - - `banned_at: optional number` + - `output_image_tokens: optional number` - - `email: optional string` + The aggregated number of image output tokens used. - - `enabled: optional boolean` + - `output_text_tokens: optional number` - - `name: optional string` + The aggregated number of text output tokens used. - - `picture: optional string` + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/users/$USER_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `service_tier: optional string` -#### Response + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -```json -{ - "id": "id", - "added_at": 0, - "object": "organization.user", - "api_key_last_used_at": 0, - "created": 0, - "developer_persona": "developer_persona", - "email": "email", - "is_default": true, - "is_scale_tier_authorized_purchaser": true, - "is_scim_managed": true, - "is_service_account": true, - "name": "name", - "projects": { - "data": [ - { - "id": "id", - "name": "name", - "role": "role" - } - ], - "object": "list" - }, - "role": "role", - "technical_level": "technical_level", - "user": { - "id": "id", - "object": "user", - "banned": true, - "banned_at": 0, - "email": "email", - "enabled": true, - "name": "name", - "picture": "picture" - } -} -``` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -#### Response + The aggregated embeddings usage details of the specific time bucket. -```json -{ - "object": "organization.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 -} -``` + - `input_tokens: number` -## Modify user + The aggregated number of input tokens used. -**post** `/organization/users/{user_id}` + - `num_model_requests: number` -Modifies a user's role in the organization. + The count of requests made to the model. -### Path Parameters + - `object: "organization.usage.embeddings.result"` -- `user_id: string` + - `"organization.usage.embeddings.result"` -### Body Parameters + - `api_key_id: optional string` -- `developer_persona: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Developer persona metadata. + - `model: optional string` -- `role: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - `owner` or `reader` + - `project_id: optional string` -- `role_id: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Role ID to assign to the user. + - `user_id: optional string` -- `technical_level: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Technical level metadata. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` -### Returns + The aggregated moderations usage details of the specific time bucket. -- `OrganizationUser object { id, added_at, object, 13 more }` + - `input_tokens: number` - Represents an individual `user` within an organization. + The aggregated number of input tokens used. - - `id: string` + - `num_model_requests: number` - The identifier, which can be referenced in API endpoints + The count of requests made to the model. - - `added_at: number` + - `object: "organization.usage.moderations.result"` - The Unix timestamp (in seconds) of when the user was added. + - `"organization.usage.moderations.result"` - - `object: "organization.user"` + - `api_key_id: optional string` - The object type, which is always `organization.user` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"organization.user"` + - `model: optional string` - - `api_key_last_used_at: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - The Unix timestamp (in seconds) of the user's last API key usage. + - `project_id: optional string` - - `created: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the user was created. + - `user_id: optional string` - - `developer_persona: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The developer persona metadata for the user. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `email: optional string` + The aggregated images usage details of the specific time bucket. - The email address of the user + - `images: number` - - `is_default: optional boolean` + The number of images processed. - Whether this is the organization's default user. + - `num_model_requests: number` - - `is_scale_tier_authorized_purchaser: optional boolean` + The count of requests made to the model. - Whether the user is an authorized purchaser for Scale Tier. + - `object: "organization.usage.images.result"` - - `is_scim_managed: optional boolean` + - `"organization.usage.images.result"` - Whether the user is managed through SCIM. + - `api_key_id: optional string` - - `is_service_account: optional boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the user is a service account. + - `model: optional string` - - `name: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The name of the user + - `project_id: optional string` - - `projects: optional object { data, object }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Projects associated with the user, if included. + - `size: optional string` - - `data: array of object { id, name, role }` + When `group_by=size`, this field provides the image size of the grouped usage result. - - `id: optional string` + - `source: optional string` - - `name: optional string` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `role: optional string` + - `user_id: optional string` - - `object: "list"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"list"` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `role: optional string` + The aggregated audio speeches usage details of the specific time bucket. - `owner` or `reader` + - `characters: number` - - `technical_level: optional string` + The number of characters processed. - The technical level metadata for the user. + - `num_model_requests: number` - - `user: optional object { id, object, banned, 5 more }` + The count of requests made to the model. - Nested user details. + - `object: "organization.usage.audio_speeches.result"` - - `id: string` + - `"organization.usage.audio_speeches.result"` - - `object: "user"` + - `api_key_id: optional string` - - `"user"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `banned: optional boolean` + - `model: optional string` - - `banned_at: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `email: optional string` + - `project_id: optional string` - - `enabled: optional boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: optional string` + - `user_id: optional string` - - `picture: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -```http -curl https://api.openai.com/v1/organization/users/$USER_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + The aggregated audio transcriptions usage details of the specific time bucket. -#### Response + - `num_model_requests: number` -```json -{ - "id": "id", - "added_at": 0, - "object": "organization.user", - "api_key_last_used_at": 0, - "created": 0, - "developer_persona": "developer_persona", - "email": "email", - "is_default": true, - "is_scale_tier_authorized_purchaser": true, - "is_scim_managed": true, - "is_service_account": true, - "name": "name", - "projects": { - "data": [ - { - "id": "id", - "name": "name", - "role": "role" - } - ], - "object": "list" - }, - "role": "role", - "technical_level": "technical_level", - "user": { - "id": "id", - "object": "user", - "banned": true, - "banned_at": 0, - "email": "email", - "enabled": true, - "name": "name", - "picture": "picture" - } -} -``` + The count of requests made to the model. -### Example + - `object: "organization.usage.audio_transcriptions.result"` -```http -curl -X POST https://api.openai.com/v1/organization/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role": "owner" - }' -``` + - `"organization.usage.audio_transcriptions.result"` -#### Response + - `seconds: number` -```json -{ - "object": "organization.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 -} -``` + The number of seconds processed. -## Delete user + - `api_key_id: optional string` -**delete** `/organization/users/{user_id}` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Deletes a user from the organization. + - `model: optional string` -### Path Parameters + When `group_by=model`, this field provides the model name of the grouped usage result. -- `user_id: string` + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `id: string` + - `user_id: optional string` -- `deleted: boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `object: "organization.user.deleted"` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `"organization.user.deleted"` + The aggregated vector stores usage details of the specific time bucket. -### Example + - `object: "organization.usage.vector_stores.result"` -```http -curl https://api.openai.com/v1/organization/users/$USER_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.usage.vector_stores.result"` -#### Response + - `usage_bytes: number` -```json -{ - "id": "id", - "deleted": true, - "object": "organization.user.deleted" -} -``` + The vector stores usage in bytes. -### Example + - `project_id: optional string` -```http -curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -```json -{ - "object": "organization.user.deleted", - "id": "user_abc", - "deleted": true -} -``` + The aggregated code interpreter sessions usage details of the specific time bucket. -## Domain Types + - `num_sessions: number` -### Organization User + The number of code interpreter sessions. -- `OrganizationUser object { id, added_at, object, 13 more }` + - `object: "organization.usage.code_interpreter_sessions.result"` - Represents an individual `user` within an organization. + - `"organization.usage.code_interpreter_sessions.result"` - - `id: string` + - `project_id: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `added_at: number` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The Unix timestamp (in seconds) of when the user was added. + The aggregated file search calls usage details of the specific time bucket. - - `object: "organization.user"` + - `num_requests: number` - The object type, which is always `organization.user` + The count of file search calls. - - `"organization.user"` + - `object: "organization.usage.file_searches.result"` - - `api_key_last_used_at: optional number` + - `"organization.usage.file_searches.result"` - The Unix timestamp (in seconds) of the user's last API key usage. + - `api_key_id: optional string` - - `created: optional number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The Unix timestamp (in seconds) of when the user was created. + - `project_id: optional string` - - `developer_persona: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The developer persona metadata for the user. + - `user_id: optional string` - - `email: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The email address of the user + - `vector_store_id: optional string` - - `is_default: optional boolean` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - Whether this is the organization's default user. + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `is_scale_tier_authorized_purchaser: optional boolean` + The aggregated web search calls usage details of the specific time bucket. - Whether the user is an authorized purchaser for Scale Tier. + - `num_model_requests: number` - - `is_scim_managed: optional boolean` + The count of model requests. - Whether the user is managed through SCIM. + - `num_requests: number` - - `is_service_account: optional boolean` + The count of web search calls. - Whether the user is a service account. + - `object: "organization.usage.web_searches.result"` - - `name: optional string` + - `"organization.usage.web_searches.result"` - The name of the user + - `api_key_id: optional string` - - `projects: optional object { data, object }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Projects associated with the user, if included. + - `context_level: optional string` - - `data: array of object { id, name, role }` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `id: optional string` + - `model: optional string` - - `name: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `role: optional string` + - `project_id: optional string` - - `object: "list"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"list"` + - `user_id: optional string` - - `role: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - `owner` or `reader` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `technical_level: optional string` + The aggregated costs details of the specific time bucket. - The technical level metadata for the user. + - `object: "organization.costs.result"` - - `user: optional object { id, object, banned, 5 more }` + - `"organization.costs.result"` - Nested user details. + - `amount: optional object { currency, value }` - - `id: string` + The monetary value in its associated currency. - - `object: "user"` + - `currency: optional string` - - `"user"` + Lowercase ISO-4217 currency e.g. "usd" - - `banned: optional boolean` + - `value: optional number` - - `banned_at: optional number` + The numeric value of the cost. - - `email: optional string` + - `api_key_id: optional string` - - `enabled: optional boolean` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `name: optional string` + - `line_item: optional string` - - `picture: optional string` + When `group_by=line_item`, this field provides the line item of the grouped costs result. -### User Delete Response + - `project_id: optional string` -- `UserDeleteResponse object { id, deleted, object }` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `id: string` + - `quantity: optional number` - - `deleted: boolean` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `object: "organization.user.deleted"` + - `start_time: number` - - `"organization.user.deleted"` +- `has_more: boolean` -# Roles +- `next_page: string` -## List user organization role assignments +- `object: "page"` -**get** `/organization/users/{user_id}/roles` + - `"page"` -Lists the organization roles assigned to a user within the organization. +### Example -### Path Parameters +```http +curl https://api.openai.com/v1/organization/usage/code_interpreter_sessions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` -- `user_id: string` +#### Response -### Query Parameters +```json +{ + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" +} +``` -- `after: optional string` +### Example - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles. +```http +curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" +``` -- `limit: optional number` +#### Response - A limit on the number of organization role assignments to return. +```json +{ + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.code_interpreter_sessions.result", + "num_sessions": 1, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null +} +``` -- `order: optional "asc" or "desc"` +## Completions - Sort order for the returned organization roles. +**get** `/organization/usage/completions` - - `"asc"` +Get completions usage details for the organization. - - `"desc"` +### Query Parameters -### Returns +- `start_time: number` -- `data: array of object { id, assignment_sources, created_at, 9 more }` + Start time (Unix seconds) of the query time range, inclusive. - Role assignments returned in the current page. +- `api_key_ids: optional array of string` - - `id: string` + Return only usage for these API keys. - Identifier for the role. +- `batch: optional boolean` - - `assignment_sources: array of object { principal_id, principal_type }` + If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both. - Principals from which the role assignment is inherited, when available. +- `bucket_width: optional "1m" or "1h" or "1d"` - - `principal_id: string` + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - `principal_type: string` + - `"1m"` - - `created_at: number` + - `"1h"` - When the role was created. + - `"1d"` - - `created_by: string` +- `end_time: optional number` - Identifier of the actor who created the role. + End time (Unix seconds) of the query time range, exclusive. - - `created_by_user_obj: map[unknown]` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 3 more` - User details for the actor that created the role, when available. + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier` or any combination of them. - - `description: string` + - `"project_id"` - Description of the role. + - `"user_id"` - - `metadata: map[unknown]` + - `"api_key_id"` - Arbitrary metadata stored on the role. + - `"model"` - - `name: string` + - `"batch"` - Name of the role. + - `"service_tier"` - - `permissions: array of string` +- `limit: optional number` - Permissions associated with the role. + Specifies the number of buckets to return. - - `predefined_role: boolean` + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - Whether the role is predefined by OpenAI. +- `models: optional array of string` - - `resource_type: string` + Return only usage for these models. - Resource type the role applies to. +- `page: optional string` - - `updated_at: number` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - When the role was last updated. +- `project_ids: optional array of string` -- `has_more: boolean` + Return only usage for these projects. - Whether additional assignments are available when paginating. +- `user_ids: optional array of string` -- `next: string` + Return only usage for these users. - Cursor to fetch the next page of results, or `null` when there are no more assignments. +### Returns -- `object: "list"` +- `data: array of object { end_time, object, results, start_time }` - Always `list`. + - `end_time: number` - - `"list"` + - `object: "bucket"` -### Example + - `"bucket"` -```http -curl https://api.openai.com/v1/organization/users/$USER_ID/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -#### Response + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -```json -{ - "data": [ - { - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + The aggregated completions usage details of the specific time bucket. -### Example + - `input_tokens: number` -```http -curl https://api.openai.com/v1/organization/users/user_abc123/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -#### Response + - `num_model_requests: number` -```json -{ - "object": "list", - "data": [ - { - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false, - "description": "Allows managing organization groups", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": { - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com" - }, - "metadata": {} - } - ], - "has_more": false, - "next": null -} -``` + The count of requests made to the model. -## Assign organization role to user + - `object: "organization.usage.completions.result"` -**post** `/organization/users/{user_id}/roles` + - `"organization.usage.completions.result"` -Assigns an organization role to a user within the organization. + - `output_tokens: number` -### Path Parameters + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `user_id: string` + - `api_key_id: optional string` -### Body Parameters + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `role_id: string` + - `batch: optional boolean` - Identifier of the role to assign. + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -### Returns + - `input_audio_tokens: optional number` -- `object: "user.role"` + The aggregated number of uncached audio input tokens used. - Always `user.role`. + - `input_cache_write_tokens: optional number` - - `"user.role"` + The aggregated number of input tokens written to the cache. -- `role: Role` + - `input_cached_audio_tokens: optional number` - Details about a role that can be assigned through the public Roles API. + The aggregated number of cached audio input tokens used. - - `id: string` + - `input_cached_image_tokens: optional number` - Identifier for the role. + The aggregated number of cached image input tokens used. - - `description: string` + - `input_cached_text_tokens: optional number` - Optional description of the role. + The aggregated number of cached text input tokens used. - - `name: string` + - `input_cached_tokens: optional number` - Unique name for the role. + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `object: "role"` + - `input_image_tokens: optional number` - Always `role`. + The aggregated number of uncached image input tokens used. - - `"role"` + - `input_text_tokens: optional number` - - `permissions: array of string` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - Permissions granted by the role. + - `input_uncached_tokens: optional number` - - `predefined_role: boolean` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - Whether the role is predefined and managed by OpenAI. + - `model: optional string` - - `resource_type: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `output_audio_tokens: optional number` -- `user: OrganizationUser` + The aggregated number of audio output tokens used. - Represents an individual `user` within an organization. + - `output_image_tokens: optional number` - - `id: string` + The aggregated number of image output tokens used. - The identifier, which can be referenced in API endpoints + - `output_text_tokens: optional number` - - `added_at: number` + The aggregated number of text output tokens used. - The Unix timestamp (in seconds) of when the user was added. + - `project_id: optional string` - - `object: "organization.user"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The object type, which is always `organization.user` + - `service_tier: optional string` - - `"organization.user"` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `api_key_last_used_at: optional number` + - `user_id: optional string` - The Unix timestamp (in seconds) of the user's last API key usage. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `created: optional number` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - The Unix timestamp (in seconds) of when the user was created. + The aggregated embeddings usage details of the specific time bucket. - - `developer_persona: optional string` + - `input_tokens: number` - The developer persona metadata for the user. + The aggregated number of input tokens used. - - `email: optional string` + - `num_model_requests: number` - The email address of the user + The count of requests made to the model. - - `is_default: optional boolean` + - `object: "organization.usage.embeddings.result"` - Whether this is the organization's default user. + - `"organization.usage.embeddings.result"` - - `is_scale_tier_authorized_purchaser: optional boolean` + - `api_key_id: optional string` - Whether the user is an authorized purchaser for Scale Tier. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `is_scim_managed: optional boolean` + - `model: optional string` - Whether the user is managed through SCIM. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `is_service_account: optional boolean` + - `project_id: optional string` - Whether the user is a service account. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: optional string` + - `user_id: optional string` - The name of the user + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `projects: optional object { data, object }` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - Projects associated with the user, if included. + The aggregated moderations usage details of the specific time bucket. - - `data: array of object { id, name, role }` + - `input_tokens: number` - - `id: optional string` + The aggregated number of input tokens used. - - `name: optional string` + - `num_model_requests: number` - - `role: optional string` + The count of requests made to the model. - - `object: "list"` + - `object: "organization.usage.moderations.result"` - - `"list"` + - `"organization.usage.moderations.result"` - - `role: optional string` + - `api_key_id: optional string` - `owner` or `reader` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `technical_level: optional string` + - `model: optional string` - The technical level metadata for the user. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `user: optional object { id, object, banned, 5 more }` + - `project_id: optional string` - Nested user details. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - - `object: "user"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"user"` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `banned: optional boolean` + The aggregated images usage details of the specific time bucket. - - `banned_at: optional number` + - `images: number` - - `email: optional string` + The number of images processed. - - `enabled: optional boolean` + - `num_model_requests: number` - - `name: optional string` + The count of requests made to the model. - - `picture: optional string` + - `object: "organization.usage.images.result"` -### Example + - `"organization.usage.images.result"` -```http -curl https://api.openai.com/v1/organization/users/$USER_ID/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "role_id": "role_id" - }' -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "object": "user.role", - "role": { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" - }, - "user": { - "id": "id", - "added_at": 0, - "object": "organization.user", - "api_key_last_used_at": 0, - "created": 0, - "developer_persona": "developer_persona", - "email": "email", - "is_default": true, - "is_scale_tier_authorized_purchaser": true, - "is_scim_managed": true, - "is_service_account": true, - "name": "name", - "projects": { - "data": [ - { - "id": "id", - "name": "name", - "role": "role" - } - ], - "object": "list" - }, - "role": "role", - "technical_level": "technical_level", - "user": { - "id": "id", - "object": "user", - "banned": true, - "banned_at": 0, - "email": "email", - "enabled": true, - "name": "name", - "picture": "picture" - } - } -} -``` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_id": "role_01J1F8ROLE01" - }' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "object": "user.role", - "user": { - "object": "organization.user", - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com", - "role": "owner", - "added_at": 1711470000 - }, - "role": { - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false - } -} -``` + - `size: optional string` -## Retrieve user organization role + When `group_by=size`, this field provides the image size of the grouped usage result. -**get** `/organization/users/{user_id}/roles/{role_id}` + - `source: optional string` -Retrieves an organization role assigned to a user. + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -### Path Parameters + - `user_id: optional string` -- `user_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `role_id: string` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -### Returns + The aggregated audio speeches usage details of the specific time bucket. -- `id: string` + - `characters: number` - Identifier for the role. + The number of characters processed. -- `assignment_sources: array of object { principal_id, principal_type }` + - `num_model_requests: number` - Principals from which the role assignment is inherited, when available. + The count of requests made to the model. - - `principal_id: string` + - `object: "organization.usage.audio_speeches.result"` - - `principal_type: string` + - `"organization.usage.audio_speeches.result"` -- `created_at: number` + - `api_key_id: optional string` - When the role was created. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `created_by: string` + - `model: optional string` - Identifier of the actor who created the role. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `created_by_user_obj: map[unknown]` + - `project_id: optional string` - User details for the actor that created the role, when available. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `description: string` + - `user_id: optional string` - Description of the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `metadata: map[unknown]` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - Arbitrary metadata stored on the role. + The aggregated audio transcriptions usage details of the specific time bucket. -- `name: string` + - `num_model_requests: number` - Name of the role. + The count of requests made to the model. -- `permissions: array of string` + - `object: "organization.usage.audio_transcriptions.result"` - Permissions associated with the role. + - `"organization.usage.audio_transcriptions.result"` -- `predefined_role: boolean` + - `seconds: number` - Whether the role is predefined by OpenAI. + The number of seconds processed. -- `resource_type: string` + - `api_key_id: optional string` - Resource type the role applies to. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `updated_at: number` + - `model: optional string` - When the role was last updated. + When `group_by=model`, this field provides the model name of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/organization/users/$USER_ID/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -```http -curl https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated vector stores usage details of the specific time bucket. -#### Response + - `object: "organization.usage.vector_stores.result"` -```json -{ - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false, - "description": "Allows managing organization groups", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": null, - "metadata": {}, - "assignment_sources": null -} -``` + - `"organization.usage.vector_stores.result"` -## Unassign organization role from user + - `usage_bytes: number` -**delete** `/organization/users/{user_id}/roles/{role_id}` + The vector stores usage in bytes. -Unassigns an organization role from a user within the organization. + - `project_id: optional string` -### Path Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `user_id: string` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -- `role_id: string` + The aggregated code interpreter sessions usage details of the specific time bucket. -### Returns + - `num_sessions: number` -- `deleted: boolean` + The number of code interpreter sessions. - Whether the assignment was removed. + - `object: "organization.usage.code_interpreter_sessions.result"` -- `object: string` + - `"organization.usage.code_interpreter_sessions.result"` - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/users/$USER_ID/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -#### Response + The aggregated file search calls usage details of the specific time bucket. -```json -{ - "deleted": true, - "object": "object" -} -``` + - `num_requests: number` -### Example + The count of file search calls. -```http -curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `object: "organization.usage.file_searches.result"` -#### Response + - `"organization.usage.file_searches.result"` -```json -{ - "object": "user.role.deleted", - "deleted": true -} -``` + - `api_key_id: optional string` -## Domain Types + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Role List Response + - `project_id: optional string` -- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Detailed information about a role assignment entry returned when listing assignments. + - `user_id: optional string` + + When `group_by=user_id`, this field provides the user ID of the grouped usage result. + + - `vector_store_id: optional string` + + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. + + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` + + The aggregated web search calls usage details of the specific time bucket. + + - `num_model_requests: number` + + The count of model requests. + + - `num_requests: number` + + The count of web search calls. + + - `object: "organization.usage.web_searches.result"` - - `id: string` + - `"organization.usage.web_searches.result"` - Identifier for the role. + - `api_key_id: optional string` - - `assignment_sources: array of object { principal_id, principal_type }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Principals from which the role assignment is inherited, when available. + - `context_level: optional string` - - `principal_id: string` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `principal_type: string` + - `model: optional string` - - `created_at: number` + When `group_by=model`, this field provides the model name of the grouped usage result. - When the role was created. + - `project_id: optional string` - - `created_by: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier of the actor who created the role. + - `user_id: optional string` - - `created_by_user_obj: map[unknown]` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - User details for the actor that created the role, when available. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `description: string` + The aggregated costs details of the specific time bucket. - Description of the role. + - `object: "organization.costs.result"` - - `metadata: map[unknown]` + - `"organization.costs.result"` - Arbitrary metadata stored on the role. + - `amount: optional object { currency, value }` - - `name: string` + The monetary value in its associated currency. - Name of the role. + - `currency: optional string` - - `permissions: array of string` + Lowercase ISO-4217 currency e.g. "usd" - Permissions associated with the role. + - `value: optional number` - - `predefined_role: boolean` + The numeric value of the cost. - Whether the role is predefined by OpenAI. + - `api_key_id: optional string` - - `resource_type: string` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - Resource type the role applies to. + - `line_item: optional string` - - `updated_at: number` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - When the role was last updated. + - `project_id: optional string` -### Role Create Response + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -- `RoleCreateResponse object { object, role, user }` + - `quantity: optional number` - Role assignment linking a user to a role. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `object: "user.role"` + - `start_time: number` - Always `user.role`. +- `has_more: boolean` - - `"user.role"` +- `next_page: string` - - `role: Role` +- `object: "page"` - Details about a role that can be assigned through the public Roles API. + - `"page"` - - `id: string` +### Example - Identifier for the role. +```http +curl https://api.openai.com/v1/organization/usage/completions \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `description: string` +#### Response - Optional description of the role. +```json +{ + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" +} +``` - - `name: string` +### Example - Unique name for the role. +```http +curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" +``` - - `object: "role"` +#### Response - Always `role`. +```json +{ + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.completions.result", + "input_tokens": 1000, + "input_cached_tokens": 400, + "input_cache_write_tokens": 100, + "input_uncached_tokens": 500, + "output_tokens": 500, + "input_text_tokens": 400, + "output_text_tokens": 400, + "input_cached_text_tokens": 300, + "input_audio_tokens": 50, + "input_cached_audio_tokens": 50, + "output_audio_tokens": 50, + "input_image_tokens": 50, + "input_cached_image_tokens": 50, + "output_image_tokens": 50, + "num_model_requests": 5, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null, + "batch": null, + "service_tier": null + } + ] + } + ], + "has_more": true, + "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" +} +``` - - `"role"` +## Costs - - `permissions: array of string` +**get** `/organization/costs` - Permissions granted by the role. +Get costs details for the organization. - - `predefined_role: boolean` +### Query Parameters - Whether the role is predefined and managed by OpenAI. +- `start_time: number` - - `resource_type: string` + Start time (Unix seconds) of the query time range, inclusive. - Resource type the role is bound to (for example `api.organization` or `api.project`). +- `api_key_ids: optional array of string` - - `user: OrganizationUser` + Return only costs for these API keys. - Represents an individual `user` within an organization. +- `bucket_width: optional "1d"` - - `id: string` + Width of each time bucket in response. Currently only `1d` is supported, default to `1d`. - The identifier, which can be referenced in API endpoints + - `"1d"` - - `added_at: number` +- `end_time: optional number` - The Unix timestamp (in seconds) of when the user was added. + End time (Unix seconds) of the query time range, exclusive. - - `object: "organization.user"` +- `group_by: optional array of "project_id" or "line_item" or "api_key_id"` - The object type, which is always `organization.user` + Group the costs by the specified fields. Support fields include `project_id`, `line_item`, `api_key_id` and any combination of them. - - `"organization.user"` + - `"project_id"` - - `api_key_last_used_at: optional number` + - `"line_item"` - The Unix timestamp (in seconds) of the user's last API key usage. + - `"api_key_id"` - - `created: optional number` +- `limit: optional number` - The Unix timestamp (in seconds) of when the user was created. + A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7. - - `developer_persona: optional string` +- `page: optional string` - The developer persona metadata for the user. + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - - `email: optional string` +- `project_ids: optional array of string` - The email address of the user + Return only costs for these projects. - - `is_default: optional boolean` +### Returns - Whether this is the organization's default user. +- `data: array of object { end_time, object, results, start_time }` - - `is_scale_tier_authorized_purchaser: optional boolean` + - `end_time: number` - Whether the user is an authorized purchaser for Scale Tier. + - `object: "bucket"` - - `is_scim_managed: optional boolean` + - `"bucket"` - Whether the user is managed through SCIM. + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `is_service_account: optional boolean` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - Whether the user is a service account. + The aggregated completions usage details of the specific time bucket. - - `name: optional string` + - `input_tokens: number` - The name of the user + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `projects: optional object { data, object }` + - `num_model_requests: number` - Projects associated with the user, if included. + The count of requests made to the model. - - `data: array of object { id, name, role }` + - `object: "organization.usage.completions.result"` - - `id: optional string` + - `"organization.usage.completions.result"` - - `name: optional string` + - `output_tokens: number` - - `role: optional string` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `object: "list"` + - `api_key_id: optional string` - - `"list"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `role: optional string` + - `batch: optional boolean` - `owner` or `reader` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - - `technical_level: optional string` + - `input_audio_tokens: optional number` - The technical level metadata for the user. + The aggregated number of uncached audio input tokens used. - - `user: optional object { id, object, banned, 5 more }` + - `input_cache_write_tokens: optional number` - Nested user details. + The aggregated number of input tokens written to the cache. - - `id: string` + - `input_cached_audio_tokens: optional number` - - `object: "user"` + The aggregated number of cached audio input tokens used. - - `"user"` + - `input_cached_image_tokens: optional number` - - `banned: optional boolean` + The aggregated number of cached image input tokens used. - - `banned_at: optional number` + - `input_cached_text_tokens: optional number` - - `email: optional string` + The aggregated number of cached text input tokens used. - - `enabled: optional boolean` + - `input_cached_tokens: optional number` - - `name: optional string` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `picture: optional string` + - `input_image_tokens: optional number` -### Role Retrieve Response + The aggregated number of uncached image input tokens used. -- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` + - `input_text_tokens: optional number` - Detailed information about a role assignment entry returned when listing assignments. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `id: string` + - `input_uncached_tokens: optional number` - Identifier for the role. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `assignment_sources: array of object { principal_id, principal_type }` + - `model: optional string` - Principals from which the role assignment is inherited, when available. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `principal_id: string` + - `output_audio_tokens: optional number` - - `principal_type: string` + The aggregated number of audio output tokens used. - - `created_at: number` + - `output_image_tokens: optional number` - When the role was created. + The aggregated number of image output tokens used. - - `created_by: string` + - `output_text_tokens: optional number` - Identifier of the actor who created the role. + The aggregated number of text output tokens used. - - `created_by_user_obj: map[unknown]` + - `project_id: optional string` - User details for the actor that created the role, when available. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `description: string` + - `service_tier: optional string` - Description of the role. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `metadata: map[unknown]` + - `user_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `name: string` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Name of the role. + The aggregated embeddings usage details of the specific time bucket. - - `permissions: array of string` + - `input_tokens: number` - Permissions associated with the role. + The aggregated number of input tokens used. - - `predefined_role: boolean` + - `num_model_requests: number` - Whether the role is predefined by OpenAI. + The count of requests made to the model. - - `resource_type: string` + - `object: "organization.usage.embeddings.result"` - Resource type the role applies to. + - `"organization.usage.embeddings.result"` - - `updated_at: number` + - `api_key_id: optional string` - When the role was last updated. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Role Delete Response + - `model: optional string` -- `RoleDeleteResponse object { deleted, object }` + When `group_by=model`, this field provides the model name of the grouped usage result. - Confirmation payload returned after unassigning a role. + - `project_id: optional string` - - `deleted: boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether the assignment was removed. + - `user_id: optional string` - - `object: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` -# Groups + The aggregated moderations usage details of the specific time bucket. -## List groups + - `input_tokens: number` -**get** `/organization/groups` + The aggregated number of input tokens used. -Lists all groups in the organization. + - `num_model_requests: number` -### Query Parameters + The count of requests made to the model. -- `after: optional string` + - `object: "organization.usage.moderations.result"` - A cursor for use in pagination. `after` is a group ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with group_abc, your subsequent call can include `after=group_abc` in order to fetch the next page of the list. + - `"organization.usage.moderations.result"` -- `limit: optional number` + - `api_key_id: optional string` - A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the default is 100. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `order: optional "asc" or "desc"` + - `model: optional string` - Specifies the sort order of the returned groups. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"asc"` + - `project_id: optional string` - - `"desc"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `data: array of Group` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Groups returned in the current page. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `id: string` + The aggregated images usage details of the specific time bucket. - Identifier for the group. + - `images: number` - - `created_at: number` + The number of images processed. - Unix timestamp (in seconds) when the group was created. + - `num_model_requests: number` - - `group_type: "group" or "tenant_group"` + The count of requests made to the model. - The type of the group. + - `object: "organization.usage.images.result"` - - `"group"` + - `"organization.usage.images.result"` - - `"tenant_group"` + - `api_key_id: optional string` - - `is_scim_managed: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the group is managed through SCIM and controlled by your identity provider. + - `model: optional string` - - `name: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Display name of the group. + - `project_id: optional string` -- `has_more: boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether additional groups are available when paginating. + - `size: optional string` -- `next: string` + When `group_by=size`, this field provides the image size of the grouped usage result. - Cursor to fetch the next page of results, or `null` if there are no more results. + - `source: optional string` -- `object: "list"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - Always `list`. + - `user_id: optional string` - - `"list"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -```http -curl https://api.openai.com/v1/organization/groups \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated audio speeches usage details of the specific time bucket. -#### Response + - `characters: number` -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "group_type": "group", - "is_scim_managed": true, - "name": "name" - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + The number of characters processed. -### Example + - `num_model_requests: number` -```http -curl https://api.openai.com/v1/organization/groups?limit=20&order=asc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.audio_speeches.result"` -```json -{ - "object": "list", - "data": [ - { - "object": "group", - "id": "group_01J1F8ABCDXYZ", - "name": "Support Team", - "created_at": 1711471533, - "is_scim_managed": false - } - ], - "has_more": false, - "next": null -} -``` + - `"organization.usage.audio_speeches.result"` -## Create group + - `api_key_id: optional string` -**post** `/organization/groups` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Creates a new group in the organization. + - `model: optional string` -### Body Parameters + When `group_by=model`, this field provides the model name of the grouped usage result. -- `name: string` + - `project_id: optional string` - Human readable name for the group. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `Group object { id, created_at, group_type, 2 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Details about an organization group. + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `id: string` + The aggregated audio transcriptions usage details of the specific time bucket. - Identifier for the group. + - `num_model_requests: number` - - `created_at: number` + The count of requests made to the model. - Unix timestamp (in seconds) when the group was created. + - `object: "organization.usage.audio_transcriptions.result"` - - `group_type: "group" or "tenant_group"` + - `"organization.usage.audio_transcriptions.result"` - The type of the group. + - `seconds: number` - - `"group"` + The number of seconds processed. - - `"tenant_group"` + - `api_key_id: optional string` - - `is_scim_managed: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the group is managed through SCIM and controlled by your identity provider. + - `model: optional string` - - `name: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Display name of the group. + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "name": "x" - }' -``` + - `user_id: optional string` -#### Response + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```json -{ - "id": "id", - "created_at": 0, - "group_type": "group", - "is_scim_managed": true, - "name": "name" -} -``` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -### Example + The aggregated vector stores usage details of the specific time bucket. -```http -curl -X POST https://api.openai.com/v1/organization/groups \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Support Team" - }' -``` + - `object: "organization.usage.vector_stores.result"` -#### Response + - `"organization.usage.vector_stores.result"` -```json -{ - "object": "group", - "id": "group_01J1F8ABCDXYZ", - "name": "Support Team", - "created_at": 1711471533, - "is_scim_managed": false -} -``` + - `usage_bytes: number` -## Retrieve group + The vector stores usage in bytes. -**get** `/organization/groups/{group_id}` + - `project_id: optional string` -Retrieves a group. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Path Parameters + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -- `group_id: string` + The aggregated code interpreter sessions usage details of the specific time bucket. -### Returns + - `num_sessions: number` -- `Group object { id, created_at, group_type, 2 more }` + The number of code interpreter sessions. - Details about an organization group. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `id: string` + - `"organization.usage.code_interpreter_sessions.result"` - Identifier for the group. + - `project_id: optional string` - - `created_at: number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Unix timestamp (in seconds) when the group was created. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `group_type: "group" or "tenant_group"` + The aggregated file search calls usage details of the specific time bucket. - The type of the group. + - `num_requests: number` - - `"group"` + The count of file search calls. - - `"tenant_group"` + - `object: "organization.usage.file_searches.result"` - - `is_scim_managed: boolean` + - `"organization.usage.file_searches.result"` - Whether the group is managed through SCIM and controlled by your identity provider. + - `api_key_id: optional string` - - `name: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Display name of the group. + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `user_id: optional string` -#### Response + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```json -{ - "id": "id", - "created_at": 0, - "group_type": "group", - "is_scim_managed": true, - "name": "name" -} -``` + - `vector_store_id: optional string` -### Example + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -#### Response + The aggregated web search calls usage details of the specific time bucket. -```json -{ - "id": "group_01J1F8ABCDXYZ", - "name": "Support Team", - "created_at": 1711471533, - "is_scim_managed": false, - "group_type": "group" -} -``` + - `num_model_requests: number` -## Update group + The count of model requests. -**post** `/organization/groups/{group_id}` + - `num_requests: number` -Updates a group's information. + The count of web search calls. -### Path Parameters + - `object: "organization.usage.web_searches.result"` -- `group_id: string` + - `"organization.usage.web_searches.result"` -### Body Parameters + - `api_key_id: optional string` -- `name: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - New display name for the group. + - `context_level: optional string` -### Returns + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `id: string` + - `model: optional string` - Identifier for the group. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `created_at: number` + - `project_id: optional string` - Unix timestamp (in seconds) when the group was created. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `is_scim_managed: boolean` + - `user_id: optional string` - Whether the group is managed through SCIM and controlled by your identity provider. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `name: string` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - Updated display name for the group. + The aggregated costs details of the specific time bucket. -### Example + - `object: "organization.costs.result"` -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "name": "x" - }' -``` + - `"organization.costs.result"` -#### Response + - `amount: optional object { currency, value }` -```json -{ - "id": "id", - "created_at": 0, - "is_scim_managed": true, - "name": "name" -} -``` + The monetary value in its associated currency. -### Example + - `currency: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Escalations" - }' -``` + Lowercase ISO-4217 currency e.g. "usd" -#### Response + - `value: optional number` -```json -{ - "id": "group_01J1F8ABCDXYZ", - "name": "Escalations", - "created_at": 1711471533, - "is_scim_managed": false -} -``` + The numeric value of the cost. -## Delete group + - `api_key_id: optional string` -**delete** `/organization/groups/{group_id}` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. -Deletes a group from the organization. + - `line_item: optional string` -### Path Parameters + When `group_by=line_item`, this field provides the line item of the grouped costs result. -- `group_id: string` + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -- `id: string` + - `quantity: optional number` - Identifier of the deleted group. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -- `deleted: boolean` + - `start_time: number` - Whether the group was deleted. +- `has_more: boolean` -- `object: "group.deleted"` +- `next_page: string` - Always `group.deleted`. +- `object: "page"` - - `"group.deleted"` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ - -X DELETE \ +curl https://api.openai.com/v1/organization/costs \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -17408,626 +19546,567 @@ curl https://api.openai.com/v1/organization/groups/$GROUP_ID \ ```json { - "id": "id", - "deleted": true, - "object": "group.deleted" + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "group.deleted", - "id": "group_01J1F8ABCDXYZ", - "deleted": true + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": null, + "project_id": null, + "api_key_id": null, + "quantity": null + } + ] + } + ], + "has_more": false, + "next_page": null } ``` -## Domain Types - -### Group - -- `Group object { id, created_at, group_type, 2 more }` - - Details about an organization group. - - - `id: string` - - Identifier for the group. - - - `created_at: number` +## Embeddings - Unix timestamp (in seconds) when the group was created. +**get** `/organization/usage/embeddings` - - `group_type: "group" or "tenant_group"` +Get embeddings usage details for the organization. - The type of the group. +### Query Parameters - - `"group"` +- `start_time: number` - - `"tenant_group"` + Start time (Unix seconds) of the query time range, inclusive. - - `is_scim_managed: boolean` +- `api_key_ids: optional array of string` - Whether the group is managed through SCIM and controlled by your identity provider. + Return only usage for these API keys. - - `name: string` +- `bucket_width: optional "1m" or "1h" or "1d"` - Display name of the group. + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. -### Group Update Response + - `"1m"` -- `GroupUpdateResponse object { id, created_at, is_scim_managed, name }` + - `"1h"` - Response returned after updating a group. + - `"1d"` - - `id: string` +- `end_time: optional number` - Identifier for the group. + End time (Unix seconds) of the query time range, exclusive. - - `created_at: number` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` - Unix timestamp (in seconds) when the group was created. + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. - - `is_scim_managed: boolean` + - `"project_id"` - Whether the group is managed through SCIM and controlled by your identity provider. + - `"user_id"` - - `name: string` + - `"api_key_id"` - Updated display name for the group. + - `"model"` -### Group Delete Response +- `limit: optional number` -- `GroupDeleteResponse object { id, deleted, object }` + Specifies the number of buckets to return. - Confirmation payload returned after deleting a group. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - - `id: string` +- `models: optional array of string` - Identifier of the deleted group. + Return only usage for these models. - - `deleted: boolean` +- `page: optional string` - Whether the group was deleted. + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - - `object: "group.deleted"` +- `project_ids: optional array of string` - Always `group.deleted`. + Return only usage for these projects. - - `"group.deleted"` +- `user_ids: optional array of string` -# Users + Return only usage for these users. -## List group users +### Returns -**get** `/organization/groups/{group_id}/users` +- `data: array of object { end_time, object, results, start_time }` -Lists the users assigned to a group. + - `end_time: number` -### Path Parameters + - `object: "bucket"` -- `group_id: string` + - `"bucket"` -### Query Parameters + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -- `after: optional string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - A cursor for use in pagination. Provide the ID of the last user from the previous list response to retrieve the next page. + The aggregated completions usage details of the specific time bucket. -- `limit: optional number` + - `input_tokens: number` - A limit on the number of users to be returned. Limit can range between 0 and 1000, and the default is 100. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `order: optional "asc" or "desc"` + - `num_model_requests: number` - Specifies the sort order of users in the list. + The count of requests made to the model. - - `"asc"` + - `object: "organization.usage.completions.result"` - - `"desc"` + - `"organization.usage.completions.result"` -### Returns + - `output_tokens: number` -- `data: array of OrganizationGroupUser` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Users in the current page. + - `api_key_id: optional string` - - `id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `batch: optional boolean` - - `email: string` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - The email address of the user. + - `input_audio_tokens: optional number` - - `name: string` + The aggregated number of uncached audio input tokens used. - The name of the user. + - `input_cache_write_tokens: optional number` -- `has_more: boolean` + The aggregated number of input tokens written to the cache. - Whether more users are available when paginating. + - `input_cached_audio_tokens: optional number` -- `next: string` + The aggregated number of cached audio input tokens used. - Cursor to fetch the next page of results, or `null` when no further users are available. + - `input_cached_image_tokens: optional number` -- `object: "list"` + The aggregated number of cached image input tokens used. - Always `list`. + - `input_cached_text_tokens: optional number` - - `"list"` + The aggregated number of cached text input tokens used. -### Example + - `input_cached_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -#### Response + - `input_image_tokens: optional number` -```json -{ - "data": [ - { - "id": "id", - "email": "email", - "name": "name" - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + The aggregated number of uncached image input tokens used. -### Example + - `input_text_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users?limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. -#### Response + - `input_uncached_tokens: optional number` -```json -{ - "object": "list", - "data": [ - { - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com" - } - ], - "has_more": false, - "next": null -} -``` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. -## Add group user + - `model: optional string` -**post** `/organization/groups/{group_id}/users` + When `group_by=model`, this field provides the model name of the grouped usage result. -Adds a user to a group. + - `output_audio_tokens: optional number` -### Path Parameters + The aggregated number of audio output tokens used. -- `group_id: string` + - `output_image_tokens: optional number` -### Body Parameters + The aggregated number of image output tokens used. -- `user_id: string` + - `output_text_tokens: optional number` - Identifier of the user to add to the group. + The aggregated number of text output tokens used. -### Returns + - `project_id: optional string` -- `group_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier of the group the user was added to. + - `service_tier: optional string` -- `object: "group.user"` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - Always `group.user`. + - `user_id: optional string` - - `"group.user"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `user_id: string` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Identifier of the user that was added. + The aggregated embeddings usage details of the specific time bucket. -### Example + - `input_tokens: number` -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "user_id": "user_id" - }' -``` + The aggregated number of input tokens used. -#### Response + - `num_model_requests: number` -```json -{ - "group_id": "group_id", - "object": "group.user", - "user_id": "user_id" -} -``` + The count of requests made to the model. -### Example + - `object: "organization.usage.embeddings.result"` -```http -curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "user_id": "user_abc123" - }' -``` + - `"organization.usage.embeddings.result"` -#### Response + - `api_key_id: optional string` -```json -{ - "object": "group.user", - "user_id": "user_abc123", - "group_id": "group_01J1F8ABCDXYZ" -} -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Retrieve group user + - `model: optional string` -**get** `/organization/groups/{group_id}/users/{user_id}` + When `group_by=model`, this field provides the model name of the grouped usage result. -Retrieves a user in a group. + - `project_id: optional string` -### Path Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `group_id: string` + - `user_id: optional string` -- `user_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Returns + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` -- `id: string` + The aggregated moderations usage details of the specific time bucket. - Identifier for the user. + - `input_tokens: number` -- `email: string` + The aggregated number of input tokens used. - Email address of the user, or `null` for users without an email. + - `num_model_requests: number` -- `is_service_account: boolean` + The count of requests made to the model. - Whether the user is a service account. + - `object: "organization.usage.moderations.result"` -- `name: string` + - `"organization.usage.moderations.result"` - Display name of the user. + - `api_key_id: optional string` -- `picture: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - URL of the user's profile picture, if available. + - `model: optional string` -- `user_type: "user" or "tenant_user"` + When `group_by=model`, this field provides the model name of the grouped usage result. - The type of user. + - `project_id: optional string` - - `"user"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"tenant_user"` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users/$USER_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -#### Response + The aggregated images usage details of the specific time bucket. -```json -{ - "id": "id", - "email": "email", - "is_service_account": true, - "name": "name", - "picture": "picture", - "user_type": "user" -} -``` + - `images: number` -### Example + The number of images processed. -```http -curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `num_model_requests: number` -#### Response + The count of requests made to the model. -```json -{ - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com", - "picture": null, - "is_service_account": false, - "user_type": "user" -} -``` + - `object: "organization.usage.images.result"` -## Remove group user + - `"organization.usage.images.result"` -**delete** `/organization/groups/{group_id}/users/{user_id}` + - `api_key_id: optional string` -Removes a user from a group. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Path Parameters + - `model: optional string` -- `group_id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. -- `user_id: string` + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `deleted: boolean` + - `size: optional string` - Whether the group membership was removed. + When `group_by=size`, this field provides the image size of the grouped usage result. -- `object: "group.user.deleted"` + - `source: optional string` - Always `group.user.deleted`. + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `"group.user.deleted"` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/users/$USER_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -#### Response + The aggregated audio speeches usage details of the specific time bucket. -```json -{ - "deleted": true, - "object": "group.user.deleted" -} -``` + - `characters: number` -### Example + The number of characters processed. -```http -curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `num_model_requests: number` -#### Response + The count of requests made to the model. -```json -{ - "object": "group.user.deleted", - "deleted": true -} -``` + - `object: "organization.usage.audio_speeches.result"` -## Domain Types + - `"organization.usage.audio_speeches.result"` -### Organization Group User + - `api_key_id: optional string` -- `OrganizationGroupUser object { id, email, name }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Represents an individual user returned when inspecting group membership. + - `model: optional string` - - `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `project_id: optional string` - - `email: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The email address of the user. + - `user_id: optional string` - - `name: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The name of the user. + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -### User Create Response + The aggregated audio transcriptions usage details of the specific time bucket. -- `UserCreateResponse object { group_id, object, user_id }` + - `num_model_requests: number` - Confirmation payload returned after adding a user to a group. + The count of requests made to the model. - - `group_id: string` + - `object: "organization.usage.audio_transcriptions.result"` - Identifier of the group the user was added to. + - `"organization.usage.audio_transcriptions.result"` - - `object: "group.user"` + - `seconds: number` - Always `group.user`. + The number of seconds processed. - - `"group.user"` + - `api_key_id: optional string` - - `user_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Identifier of the user that was added. + - `model: optional string` -### User Retrieve Response + When `group_by=model`, this field provides the model name of the grouped usage result. -- `UserRetrieveResponse object { id, email, is_service_account, 3 more }` + - `project_id: optional string` - Details about a user returned from an organization group membership lookup. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - Identifier for the user. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `email: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - Email address of the user, or `null` for users without an email. + The aggregated vector stores usage details of the specific time bucket. - - `is_service_account: boolean` + - `object: "organization.usage.vector_stores.result"` - Whether the user is a service account. + - `"organization.usage.vector_stores.result"` - - `name: string` + - `usage_bytes: number` - Display name of the user. + The vector stores usage in bytes. - - `picture: string` + - `project_id: optional string` - URL of the user's profile picture, if available. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `user_type: "user" or "tenant_user"` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - The type of user. + The aggregated code interpreter sessions usage details of the specific time bucket. - - `"user"` + - `num_sessions: number` - - `"tenant_user"` + The number of code interpreter sessions. -### User Delete Response + - `object: "organization.usage.code_interpreter_sessions.result"` -- `UserDeleteResponse object { deleted, object }` + - `"organization.usage.code_interpreter_sessions.result"` - Confirmation payload returned after removing a user from a group. + - `project_id: optional string` - - `deleted: boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether the group membership was removed. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `object: "group.user.deleted"` + The aggregated file search calls usage details of the specific time bucket. - Always `group.user.deleted`. + - `num_requests: number` - - `"group.user.deleted"` + The count of file search calls. -# Roles + - `object: "organization.usage.file_searches.result"` -## List group organization role assignments + - `"organization.usage.file_searches.result"` -**get** `/organization/groups/{group_id}/roles` + - `api_key_id: optional string` -Lists the organization roles assigned to a group within the organization. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Path Parameters + - `project_id: optional string` -- `group_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Query Parameters + - `user_id: optional string` -- `after: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles. + - `vector_store_id: optional string` -- `limit: optional number` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - A limit on the number of organization role assignments to return. + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -- `order: optional "asc" or "desc"` + The aggregated web search calls usage details of the specific time bucket. - Sort order for the returned organization roles. + - `num_model_requests: number` - - `"asc"` + The count of model requests. - - `"desc"` + - `num_requests: number` -### Returns + The count of web search calls. -- `data: array of object { id, assignment_sources, created_at, 9 more }` + - `object: "organization.usage.web_searches.result"` - Role assignments returned in the current page. + - `"organization.usage.web_searches.result"` - - `id: string` + - `api_key_id: optional string` - Identifier for the role. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `assignment_sources: array of object { principal_id, principal_type }` + - `context_level: optional string` - Principals from which the role assignment is inherited, when available. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `principal_id: string` + - `model: optional string` - - `principal_type: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `created_at: number` + - `project_id: optional string` - When the role was created. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `created_by: string` + - `user_id: optional string` - Identifier of the actor who created the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `created_by_user_obj: map[unknown]` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - User details for the actor that created the role, when available. + The aggregated costs details of the specific time bucket. - - `description: string` + - `object: "organization.costs.result"` - Description of the role. + - `"organization.costs.result"` - - `metadata: map[unknown]` + - `amount: optional object { currency, value }` - Arbitrary metadata stored on the role. + The monetary value in its associated currency. - - `name: string` + - `currency: optional string` - Name of the role. + Lowercase ISO-4217 currency e.g. "usd" - - `permissions: array of string` + - `value: optional number` - Permissions associated with the role. + The numeric value of the cost. - - `predefined_role: boolean` + - `api_key_id: optional string` - Whether the role is predefined by OpenAI. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `resource_type: string` + - `line_item: optional string` - Resource type the role applies to. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `updated_at: number` + - `project_id: optional string` - When the role was last updated. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -- `has_more: boolean` + - `quantity: optional number` - Whether additional assignments are available when paginating. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -- `next: string` + - `start_time: number` - Cursor to fetch the next page of results, or `null` when there are no more assignments. +- `has_more: boolean` -- `object: "list"` +- `next_page: string` - Always `list`. +- `object: "page"` - - `"list"` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles \ +curl https://api.openai.com/v1/organization/usage/embeddings \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -18037,709 +20116,563 @@ curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles \ { "data": [ { - "id": "id", - "assignment_sources": [ + "end_time": 0, + "object": "bucket", + "results": [ { - "principal_id": "principal_id", - "principal_type": "principal_type" + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" } ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 + "start_time": 0 } ], "has_more": true, - "next": "next", - "object": "list" + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response -```json -{ - "object": "list", - "data": [ - { - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false, - "description": "Allows managing organization groups", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": { - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com" - }, - "metadata": {} - } - ], - "has_more": false, - "next": null -} -``` - -## Assign organization role to group - -**post** `/organization/groups/{group_id}/roles` - -Assigns an organization role to a group within the organization. - -### Path Parameters - -- `group_id: string` - -### Body Parameters - -- `role_id: string` - - Identifier of the role to assign. - -### Returns - -- `group: object { id, created_at, name, 2 more }` - - Summary information about a group returned in role assignment responses. - - - `id: string` - - Identifier for the group. - - - `created_at: number` - - Unix timestamp (in seconds) when the group was created. - - - `name: string` +```json +{ + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.embeddings.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null +} +``` - Display name of the group. +## File search calls - - `object: "group"` +**get** `/organization/usage/file_search_calls` - Always `group`. +Get file search calls usage details for the organization. - - `"group"` +### Query Parameters - - `scim_managed: boolean` +- `start_time: number` - Whether the group is managed through SCIM. + Start time (Unix seconds) of the query time range, inclusive. -- `object: "group.role"` +- `api_key_ids: optional array of string` - Always `group.role`. + Return only usage for these API keys. - - `"group.role"` +- `bucket_width: optional "1m" or "1h" or "1d"` -- `role: Role` + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - Details about a role that can be assigned through the public Roles API. + - `"1m"` - - `id: string` + - `"1h"` - Identifier for the role. + - `"1d"` - - `description: string` +- `end_time: optional number` - Optional description of the role. + End time (Unix seconds) of the query time range, exclusive. - - `name: string` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "vector_store_id"` - Unique name for the role. + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `vector_store_id` or any combination of them. - - `object: "role"` + - `"project_id"` - Always `role`. + - `"user_id"` - - `"role"` + - `"api_key_id"` - - `permissions: array of string` + - `"vector_store_id"` - Permissions granted by the role. +- `limit: optional number` - - `predefined_role: boolean` + Specifies the number of buckets to return. - Whether the role is predefined and managed by OpenAI. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - - `resource_type: string` +- `page: optional string` - Resource type the role is bound to (for example `api.organization` or `api.project`). + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. -### Example +- `project_ids: optional array of string` -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "role_id": "role_id" - }' -``` + Return only usage for these projects. -#### Response +- `user_ids: optional array of string` -```json -{ - "group": { - "id": "id", - "created_at": 0, - "name": "name", - "object": "group", - "scim_managed": true - }, - "object": "group.role", - "role": { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" - } -} -``` + Return only usage for these users. -### Example +- `vector_store_ids: optional array of string` -```http -curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_id": "role_01J1F8ROLE01" - }' -``` + Return only usage for these vector stores. -#### Response +### Returns -```json -{ - "object": "group.role", - "group": { - "object": "group", - "id": "group_01J1F8ABCDXYZ", - "name": "Support Team", - "created_at": 1711471533, - "scim_managed": false - }, - "role": { - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false - } -} -``` +- `data: array of object { end_time, object, results, start_time }` -## Retrieve group organization role + - `end_time: number` -**get** `/organization/groups/{group_id}/roles/{role_id}` + - `object: "bucket"` -Retrieves an organization role assigned to a group. + - `"bucket"` -### Path Parameters + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -- `group_id: string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -- `role_id: string` + The aggregated completions usage details of the specific time bucket. -### Returns + - `input_tokens: number` -- `id: string` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Identifier for the role. + - `num_model_requests: number` -- `assignment_sources: array of object { principal_id, principal_type }` + The count of requests made to the model. - Principals from which the role assignment is inherited, when available. + - `object: "organization.usage.completions.result"` - - `principal_id: string` + - `"organization.usage.completions.result"` - - `principal_type: string` + - `output_tokens: number` -- `created_at: number` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - When the role was created. + - `api_key_id: optional string` -- `created_by: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Identifier of the actor who created the role. + - `batch: optional boolean` -- `created_by_user_obj: map[unknown]` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - User details for the actor that created the role, when available. + - `input_audio_tokens: optional number` -- `description: string` + The aggregated number of uncached audio input tokens used. - Description of the role. + - `input_cache_write_tokens: optional number` -- `metadata: map[unknown]` + The aggregated number of input tokens written to the cache. - Arbitrary metadata stored on the role. + - `input_cached_audio_tokens: optional number` -- `name: string` + The aggregated number of cached audio input tokens used. - Name of the role. + - `input_cached_image_tokens: optional number` -- `permissions: array of string` + The aggregated number of cached image input tokens used. - Permissions associated with the role. + - `input_cached_text_tokens: optional number` -- `predefined_role: boolean` + The aggregated number of cached text input tokens used. - Whether the role is predefined by OpenAI. + - `input_cached_tokens: optional number` -- `resource_type: string` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Resource type the role applies to. + - `input_image_tokens: optional number` -- `updated_at: number` + The aggregated number of uncached image input tokens used. - When the role was last updated. + - `input_text_tokens: optional number` -### Example + The aggregated number of uncached text input tokens used, excluding cache-write tokens. -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `input_uncached_tokens: optional number` -#### Response + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. -```json -{ - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 -} -``` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `output_audio_tokens: optional number` -#### Response + The aggregated number of audio output tokens used. -```json -{ - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false, - "description": "Allows managing organization groups", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": null, - "metadata": {}, - "assignment_sources": null -} -``` + - `output_image_tokens: optional number` -## Unassign organization role from group + The aggregated number of image output tokens used. -**delete** `/organization/groups/{group_id}/roles/{role_id}` + - `output_text_tokens: optional number` -Unassigns an organization role from a group within the organization. + The aggregated number of text output tokens used. -### Path Parameters + - `project_id: optional string` -- `group_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `role_id: string` + - `service_tier: optional string` -### Returns + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -- `deleted: boolean` + - `user_id: optional string` - Whether the assignment was removed. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `object: string` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + The aggregated embeddings usage details of the specific time bucket. -### Example + - `input_tokens: number` -```http -curl https://api.openai.com/v1/organization/groups/$GROUP_ID/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of input tokens used. -#### Response + - `num_model_requests: number` -```json -{ - "deleted": true, - "object": "object" -} -``` + The count of requests made to the model. -### Example + - `object: "organization.usage.embeddings.result"` -```http -curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `"organization.usage.embeddings.result"` -#### Response + - `api_key_id: optional string` -```json -{ - "object": "group.role.deleted", - "deleted": true -} -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Domain Types + - `model: optional string` -### Role List Response + When `group_by=model`, this field provides the model name of the grouped usage result. -- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` + - `project_id: optional string` - Detailed information about a role assignment entry returned when listing assignments. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - Identifier for the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `assignment_sources: array of object { principal_id, principal_type }` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - Principals from which the role assignment is inherited, when available. + The aggregated moderations usage details of the specific time bucket. - - `principal_id: string` + - `input_tokens: number` - - `principal_type: string` + The aggregated number of input tokens used. - - `created_at: number` + - `num_model_requests: number` - When the role was created. + The count of requests made to the model. - - `created_by: string` + - `object: "organization.usage.moderations.result"` - Identifier of the actor who created the role. + - `"organization.usage.moderations.result"` - - `created_by_user_obj: map[unknown]` + - `api_key_id: optional string` - User details for the actor that created the role, when available. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `description: string` + - `model: optional string` - Description of the role. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `metadata: map[unknown]` + - `project_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: string` + - `user_id: optional string` - Name of the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `permissions: array of string` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - Permissions associated with the role. + The aggregated images usage details of the specific time bucket. - - `predefined_role: boolean` + - `images: number` - Whether the role is predefined by OpenAI. + The number of images processed. - - `resource_type: string` + - `num_model_requests: number` - Resource type the role applies to. + The count of requests made to the model. - - `updated_at: number` + - `object: "organization.usage.images.result"` - When the role was last updated. + - `"organization.usage.images.result"` -### Role Create Response + - `api_key_id: optional string` -- `RoleCreateResponse object { group, object, role }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Role assignment linking a group to a role. + - `model: optional string` - - `group: object { id, created_at, name, 2 more }` + When `group_by=model`, this field provides the model name of the grouped usage result. - Summary information about a group returned in role assignment responses. + - `project_id: optional string` - - `id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier for the group. + - `size: optional string` - - `created_at: number` + When `group_by=size`, this field provides the image size of the grouped usage result. - Unix timestamp (in seconds) when the group was created. + - `source: optional string` - - `name: string` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - Display name of the group. + - `user_id: optional string` - - `object: "group"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Always `group`. + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `"group"` + The aggregated audio speeches usage details of the specific time bucket. - - `scim_managed: boolean` + - `characters: number` - Whether the group is managed through SCIM. + The number of characters processed. - - `object: "group.role"` + - `num_model_requests: number` - Always `group.role`. + The count of requests made to the model. - - `"group.role"` + - `object: "organization.usage.audio_speeches.result"` - - `role: Role` + - `"organization.usage.audio_speeches.result"` - Details about a role that can be assigned through the public Roles API. + - `api_key_id: optional string` - - `id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Identifier for the role. + - `model: optional string` - - `description: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Optional description of the role. + - `project_id: optional string` - - `name: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Unique name for the role. + - `user_id: optional string` - - `object: "role"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Always `role`. + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `"role"` + The aggregated audio transcriptions usage details of the specific time bucket. - - `permissions: array of string` + - `num_model_requests: number` - Permissions granted by the role. + The count of requests made to the model. - - `predefined_role: boolean` + - `object: "organization.usage.audio_transcriptions.result"` - Whether the role is predefined and managed by OpenAI. + - `"organization.usage.audio_transcriptions.result"` - - `resource_type: string` + - `seconds: number` - Resource type the role is bound to (for example `api.organization` or `api.project`). + The number of seconds processed. -### Role Retrieve Response + - `api_key_id: optional string` -- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Detailed information about a role assignment entry returned when listing assignments. + - `model: optional string` - - `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Identifier for the role. + - `project_id: optional string` - - `assignment_sources: array of object { principal_id, principal_type }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Principals from which the role assignment is inherited, when available. + - `user_id: optional string` - - `principal_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `principal_type: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `created_at: number` + The aggregated vector stores usage details of the specific time bucket. - When the role was created. + - `object: "organization.usage.vector_stores.result"` - - `created_by: string` + - `"organization.usage.vector_stores.result"` - Identifier of the actor who created the role. + - `usage_bytes: number` - - `created_by_user_obj: map[unknown]` + The vector stores usage in bytes. + + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. + + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` + + The aggregated code interpreter sessions usage details of the specific time bucket. + + - `num_sessions: number` - User details for the actor that created the role, when available. + The number of code interpreter sessions. - - `description: string` + - `object: "organization.usage.code_interpreter_sessions.result"` - Description of the role. + - `"organization.usage.code_interpreter_sessions.result"` - - `metadata: map[unknown]` + - `project_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: string` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - Name of the role. + The aggregated file search calls usage details of the specific time bucket. - - `permissions: array of string` + - `num_requests: number` - Permissions associated with the role. + The count of file search calls. - - `predefined_role: boolean` + - `object: "organization.usage.file_searches.result"` - Whether the role is predefined by OpenAI. + - `"organization.usage.file_searches.result"` - - `resource_type: string` + - `api_key_id: optional string` - Resource type the role applies to. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `updated_at: number` + - `project_id: optional string` - When the role was last updated. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Role Delete Response + - `user_id: optional string` -- `RoleDeleteResponse object { deleted, object }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Confirmation payload returned after unassigning a role. + - `vector_store_id: optional string` - - `deleted: boolean` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - Whether the assignment was removed. + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `object: string` + The aggregated web search calls usage details of the specific time bucket. - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + - `num_model_requests: number` -# Roles + The count of model requests. -## List organization roles + - `num_requests: number` -**get** `/organization/roles` + The count of web search calls. -Lists the roles configured for the organization. + - `object: "organization.usage.web_searches.result"` -### Query Parameters + - `"organization.usage.web_searches.result"` -- `after: optional string` + - `api_key_id: optional string` - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `limit: optional number` + - `context_level: optional string` - A limit on the number of roles to return. Defaults to 1000. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `order: optional "asc" or "desc"` + - `model: optional string` - Sort order for the returned roles. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"asc"` + - `project_id: optional string` - - `"desc"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `data: array of Role` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Roles returned in the current page. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `id: string` + The aggregated costs details of the specific time bucket. - Identifier for the role. + - `object: "organization.costs.result"` - - `description: string` + - `"organization.costs.result"` - Optional description of the role. + - `amount: optional object { currency, value }` - - `name: string` + The monetary value in its associated currency. - Unique name for the role. + - `currency: optional string` - - `object: "role"` + Lowercase ISO-4217 currency e.g. "usd" - Always `role`. + - `value: optional number` - - `"role"` + The numeric value of the cost. - - `permissions: array of string` + - `api_key_id: optional string` - Permissions granted by the role. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `predefined_role: boolean` + - `line_item: optional string` - Whether the role is predefined and managed by OpenAI. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `resource_type: string` + - `project_id: optional string` - Resource type the role is bound to (for example `api.organization` or `api.project`). + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -- `has_more: boolean` + - `quantity: optional number` - Whether more roles are available when paginating. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -- `next: string` + - `start_time: number` - Cursor to fetch the next page of results, or `null` when there are no additional roles. +- `has_more: boolean` -- `object: "list"` +- `next_page: string` - Always `list`. +- `object: "page"` - - `"list"` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/roles \ +curl https://api.openai.com/v1/organization/usage/file_search_calls \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -18749,751 +20682,590 @@ curl https://api.openai.com/v1/organization/roles \ { "data": [ { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } ], - "predefined_role": true, - "resource_type": "resource_type" + "start_time": 0 } ], "has_more": true, - "next": "next", - "object": "list" + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/roles?limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/file_search_calls?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "list", + "object": "page", "data": [ { - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.file_searches.result", + "num_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "vector_store_id": null + } + ] } ], "has_more": false, - "next": null + "next_page": null } ``` -## Create organization role - -**post** `/organization/roles` - -Creates a custom role for the organization. +## Images -### Body Parameters +**get** `/organization/usage/images` -- `permissions: array of string` +Get images usage details for the organization. - Permissions to grant to the role. +### Query Parameters -- `role_name: string` +- `start_time: number` - Unique name for the role. + Start time (Unix seconds) of the query time range, inclusive. -- `description: optional string` +- `api_key_ids: optional array of string` - Optional description of the role. + Return only usage for these API keys. -### Returns +- `bucket_width: optional "1m" or "1h" or "1d"` -- `Role object { id, description, name, 4 more }` + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - Details about a role that can be assigned through the public Roles API. + - `"1m"` - - `id: string` + - `"1h"` - Identifier for the role. + - `"1d"` - - `description: string` +- `end_time: optional number` - Optional description of the role. + End time (Unix seconds) of the query time range, exclusive. - - `name: string` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 3 more` - Unique name for the role. + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `size`, `source` or any combination of them. - - `object: "role"` + - `"project_id"` - Always `role`. + - `"user_id"` - - `"role"` + - `"api_key_id"` - - `permissions: array of string` + - `"model"` - Permissions granted by the role. + - `"size"` - - `predefined_role: boolean` + - `"source"` - Whether the role is predefined and managed by OpenAI. +- `limit: optional number` - - `resource_type: string` + Specifies the number of buckets to return. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 -### Example +- `models: optional array of string` -```http -curl https://api.openai.com/v1/organization/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "permissions": [ - "string" - ], - "role_name": "role_name" - }' -``` + Return only usage for these models. -#### Response +- `page: optional string` -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. -### Example +- `project_ids: optional array of string` -```http -curl -X POST https://api.openai.com/v1/organization/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "description": "Allows managing organization groups" - }' -``` + Return only usage for these projects. -#### Response +- `sizes: optional array of "256x256" or "512x512" or "1024x1024" or 2 more` -```json -{ - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false -} -``` + Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them. -## Retrieve organization role + - `"256x256"` -**get** `/organization/roles/{role_id}` + - `"512x512"` -Retrieves an organization role. + - `"1024x1024"` -### Path Parameters + - `"1792x1792"` -- `role_id: string` + - `"1024x1792"` -### Returns +- `sources: optional array of "image.generation" or "image.edit" or "image.variation"` -- `Role object { id, description, name, 4 more }` + Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them. - Details about a role that can be assigned through the public Roles API. + - `"image.generation"` - - `id: string` + - `"image.edit"` - Identifier for the role. + - `"image.variation"` - - `description: string` +- `user_ids: optional array of string` - Optional description of the role. + Return only usage for these users. - - `name: string` +### Returns - Unique name for the role. +- `data: array of object { end_time, object, results, start_time }` - - `object: "role"` + - `end_time: number` - Always `role`. + - `object: "bucket"` - - `"role"` + - `"bucket"` - - `permissions: array of string` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - Permissions granted by the role. + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - - `predefined_role: boolean` + The aggregated completions usage details of the specific time bucket. - Whether the role is predefined and managed by OpenAI. + - `input_tokens: number` - - `resource_type: string` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `num_model_requests: number` -### Example + The count of requests made to the model. -```http -curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `object: "organization.usage.completions.result"` -#### Response + - `"organization.usage.completions.result"` -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + - `output_tokens: number` -### Example + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -```http -curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false -} -``` + - `batch: optional boolean` -## Update organization role + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -**post** `/organization/roles/{role_id}` + - `input_audio_tokens: optional number` -Updates an existing organization role. + The aggregated number of uncached audio input tokens used. -### Path Parameters + - `input_cache_write_tokens: optional number` -- `role_id: string` + The aggregated number of input tokens written to the cache. -### Body Parameters + - `input_cached_audio_tokens: optional number` -- `description: optional string` + The aggregated number of cached audio input tokens used. - New description for the role. + - `input_cached_image_tokens: optional number` -- `permissions: optional array of string` + The aggregated number of cached image input tokens used. - Updated set of permissions for the role. + - `input_cached_text_tokens: optional number` -- `role_name: optional string` + The aggregated number of cached text input tokens used. - New name for the role. + - `input_cached_tokens: optional number` -### Returns + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `Role object { id, description, name, 4 more }` + - `input_image_tokens: optional number` - Details about a role that can be assigned through the public Roles API. + The aggregated number of uncached image input tokens used. - - `id: string` + - `input_text_tokens: optional number` - Identifier for the role. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `description: string` + - `input_uncached_tokens: optional number` - Optional description of the role. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `name: string` + - `model: optional string` - Unique name for the role. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `object: "role"` + - `output_audio_tokens: optional number` - Always `role`. + The aggregated number of audio output tokens used. - - `"role"` + - `output_image_tokens: optional number` - - `permissions: array of string` + The aggregated number of image output tokens used. - Permissions granted by the role. + - `output_text_tokens: optional number` - - `predefined_role: boolean` + The aggregated number of text output tokens used. - Whether the role is predefined and managed by OpenAI. + - `project_id: optional string` - - `resource_type: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `service_tier: optional string` -### Example + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + - `user_id: optional string` -#### Response + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -### Example + The aggregated embeddings usage details of the specific time bucket. -```http -curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_name": "API Group Manager", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "description": "Allows managing organization groups" - }' -``` + - `input_tokens: number` -#### Response + The aggregated number of input tokens used. -```json -{ - "object": "role", - "id": "role_01J1F8ROLE01", - "name": "API Group Manager", - "description": "Allows managing organization groups", - "permissions": [ - "api.groups.read", - "api.groups.write" - ], - "resource_type": "api.organization", - "predefined_role": false -} -``` + - `num_model_requests: number` -## Delete organization role + The count of requests made to the model. -**delete** `/organization/roles/{role_id}` + - `object: "organization.usage.embeddings.result"` -Deletes a custom role from the organization. + - `"organization.usage.embeddings.result"` -### Path Parameters + - `api_key_id: optional string` -- `role_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Returns + - `model: optional string` -- `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Identifier of the deleted role. + - `project_id: optional string` -- `deleted: boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether the role was deleted. + - `user_id: optional string` -- `object: "role.deleted"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Always `role.deleted`. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `"role.deleted"` + The aggregated moderations usage details of the specific time bucket. -### Example + - `input_tokens: number` -```http -curl https://api.openai.com/v1/organization/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of input tokens used. -#### Response + - `num_model_requests: number` -```json -{ - "id": "id", - "deleted": true, - "object": "role.deleted" -} -``` + The count of requests made to the model. -### Example + - `object: "organization.usage.moderations.result"` -```http -curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `"organization.usage.moderations.result"` -#### Response + - `api_key_id: optional string` -```json -{ - "object": "role.deleted", - "id": "role_01J1F8ROLE01", - "deleted": true -} -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Domain Types + - `model: optional string` -### Role + When `group_by=model`, this field provides the model name of the grouped usage result. -- `Role object { id, description, name, 4 more }` + - `project_id: optional string` - Details about a role that can be assigned through the public Roles API. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - Identifier for the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `description: string` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - Optional description of the role. + The aggregated images usage details of the specific time bucket. - - `name: string` + - `images: number` - Unique name for the role. + The number of images processed. - - `object: "role"` + - `num_model_requests: number` - Always `role`. + The count of requests made to the model. - - `"role"` + - `object: "organization.usage.images.result"` - - `permissions: array of string` + - `"organization.usage.images.result"` - Permissions granted by the role. + - `api_key_id: optional string` - - `predefined_role: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the role is predefined and managed by OpenAI. + - `model: optional string` - - `resource_type: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `project_id: optional string` -### Role Delete Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `RoleDeleteResponse object { id, deleted, object }` + - `size: optional string` - Confirmation payload returned after deleting a role. + When `group_by=size`, this field provides the image size of the grouped usage result. - - `id: string` + - `source: optional string` - Identifier of the deleted role. + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `deleted: boolean` + - `user_id: optional string` - Whether the role was deleted. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `object: "role.deleted"` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - Always `role.deleted`. + The aggregated audio speeches usage details of the specific time bucket. - - `"role.deleted"` + - `characters: number` -# Data Retention + The number of characters processed. -## Retrieve organization data retention + - `num_model_requests: number` -**get** `/organization/data_retention` + The count of requests made to the model. -Retrieves organization data retention controls. + - `object: "organization.usage.audio_speeches.result"` -### Returns + - `"organization.usage.audio_speeches.result"` -- `OrganizationDataRetention object { object, type }` + - `api_key_id: optional string` - Represents the organization's data retention control setting. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `object: "organization.data_retention"` + - `model: optional string` - The object type, which is always `organization.data_retention`. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"organization.data_retention"` + - `project_id: optional string` - - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The configured organization data retention type. + - `user_id: optional string` - - `"zero_data_retention"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"modified_abuse_monitoring"` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `"enhanced_zero_data_retention"` + The aggregated audio transcriptions usage details of the specific time bucket. - - `"enhanced_modified_abuse_monitoring"` + - `num_model_requests: number` -### Example + The count of requests made to the model. -```http -curl https://api.openai.com/v1/organization/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `object: "organization.usage.audio_transcriptions.result"` -#### Response + - `"organization.usage.audio_transcriptions.result"` -```json -{ - "object": "organization.data_retention", - "type": "zero_data_retention" -} -``` + - `seconds: number` -### Example + The number of seconds processed. -```http -curl https://api.openai.com/v1/organization/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "object": "organization.data_retention", - "type": "modified_abuse_monitoring" -} -``` + - `model: optional string` -## Update organization data retention + When `group_by=model`, this field provides the model name of the grouped usage result. -**post** `/organization/data_retention` + - `project_id: optional string` -Updates organization data retention controls. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Body Parameters + - `user_id: optional string` -- `retention_type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The desired organization data retention type. + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `"zero_data_retention"` + The aggregated vector stores usage details of the specific time bucket. - - `"modified_abuse_monitoring"` + - `object: "organization.usage.vector_stores.result"` - - `"enhanced_zero_data_retention"` + - `"organization.usage.vector_stores.result"` - - `"enhanced_modified_abuse_monitoring"` + - `usage_bytes: number` -### Returns + The vector stores usage in bytes. -- `OrganizationDataRetention object { object, type }` + - `project_id: optional string` - Represents the organization's data retention control setting. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `object: "organization.data_retention"` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - The object type, which is always `organization.data_retention`. + The aggregated code interpreter sessions usage details of the specific time bucket. - - `"organization.data_retention"` + - `num_sessions: number` - - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` + The number of code interpreter sessions. - The configured organization data retention type. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `"zero_data_retention"` + - `"organization.usage.code_interpreter_sessions.result"` - - `"modified_abuse_monitoring"` + - `project_id: optional string` - - `"enhanced_zero_data_retention"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"enhanced_modified_abuse_monitoring"` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -### Example + The aggregated file search calls usage details of the specific time bucket. -```http -curl https://api.openai.com/v1/organization/data_retention \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "retention_type": "zero_data_retention" - }' -``` + - `num_requests: number` -#### Response + The count of file search calls. -```json -{ - "object": "organization.data_retention", - "type": "zero_data_retention" -} -``` + - `object: "organization.usage.file_searches.result"` -### Example + - `"organization.usage.file_searches.result"` -```http -curl -X POST https://api.openai.com/v1/organization/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "retention_type": "modified_abuse_monitoring" - }' -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "object": "organization.data_retention", - "type": "modified_abuse_monitoring" -} -``` + - `project_id: optional string` -## Domain Types + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Organization Data Retention + - `user_id: optional string` -- `OrganizationDataRetention object { object, type }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Represents the organization's data retention control setting. + - `vector_store_id: optional string` - - `object: "organization.data_retention"` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - The object type, which is always `organization.data_retention`. + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `"organization.data_retention"` + The aggregated web search calls usage details of the specific time bucket. - - `type: "zero_data_retention" or "modified_abuse_monitoring" or "enhanced_zero_data_retention" or "enhanced_modified_abuse_monitoring"` + - `num_model_requests: number` - The configured organization data retention type. + The count of model requests. - - `"zero_data_retention"` + - `num_requests: number` - - `"modified_abuse_monitoring"` + The count of web search calls. - - `"enhanced_zero_data_retention"` + - `object: "organization.usage.web_searches.result"` - - `"enhanced_modified_abuse_monitoring"` + - `"organization.usage.web_searches.result"` -# Spend Limit + - `api_key_id: optional string` -## Retrieve organization spend limit + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -**get** `/organization/spend_limit` + - `context_level: optional string` -Get the organization's hard spend limit. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -### Returns + - `model: optional string` -- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` + When `group_by=model`, this field provides the model name of the grouped usage result. - Represents a hard spend limit configured at the organization level. + - `project_id: optional string` - - `currency: string or "USD"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The currency for the threshold amount. Currently, only `USD` is supported. + - `user_id: optional string` - - `string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"USD"` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - The currency for the threshold amount. Currently, only `USD` is supported. + The aggregated costs details of the specific time bucket. - - `"USD"` + - `object: "organization.costs.result"` - - `enforcement: object { status }` + - `"organization.costs.result"` - The current enforcement state of the hard spend limit. + - `amount: optional object { currency, value }` - - `status: string or "inactive" or "enforcing"` + The monetary value in its associated currency. - Whether the hard spend limit is currently enforcing. + - `currency: optional string` - - `string` + Lowercase ISO-4217 currency e.g. "usd" - - `"inactive" or "enforcing"` + - `value: optional number` - Whether the hard spend limit is currently enforcing. + The numeric value of the cost. - - `"inactive"` + - `api_key_id: optional string` - - `"enforcing"` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `interval: string or "month"` + - `line_item: optional string` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `string` + - `project_id: optional string` - - `"month"` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + - `quantity: optional number` - - `"month"` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `object: "organization.spend_limit"` + - `start_time: number` - The object type, which is always `organization.spend_limit`. +- `has_more: boolean` - - `"organization.spend_limit"` +- `next_page: string` - - `threshold_amount: number` +- `object: "page"` - The hard spend limit amount, in cents. + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/spend_limit \ +curl https://api.openai.com/v1/organization/usage/images \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -19501,700 +21273,567 @@ curl https://api.openai.com/v1/organization/spend_limit \ ```json { - "currency": "USD", - "enforcement": { - "status": "inactive" - }, - "interval": "month", - "object": "organization.spend_limit", - "threshold_amount": 0 + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "organization.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": null, + "source": null, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null } + ] + } + ], + "has_more": false, + "next_page": null } ``` -## Update organization spend limit - -**post** `/organization/spend_limit` - -Create or replace the organization's hard spend limit. - -### Body Parameters - -- `currency: "USD"` - - The currency for the threshold amount. Currently, only `USD` is supported. - - - `"USD"` - -- `interval: "month"` - - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +## Moderations - - `"month"` +**get** `/organization/usage/moderations` -- `threshold_amount: number` +Get moderations usage details for the organization. - The hard spend limit amount, in cents. +### Query Parameters -### Returns +- `start_time: number` -- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` + Start time (Unix seconds) of the query time range, inclusive. - Represents a hard spend limit configured at the organization level. +- `api_key_ids: optional array of string` - - `currency: string or "USD"` + Return only usage for these API keys. - The currency for the threshold amount. Currently, only `USD` is supported. +- `bucket_width: optional "1m" or "1h" or "1d"` - - `string` + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - `"USD"` + - `"1m"` - The currency for the threshold amount. Currently, only `USD` is supported. + - `"1h"` - - `"USD"` + - `"1d"` - - `enforcement: object { status }` +- `end_time: optional number` - The current enforcement state of the hard spend limit. + End time (Unix seconds) of the query time range, exclusive. - - `status: string or "inactive" or "enforcing"` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or "model"` - Whether the hard spend limit is currently enforcing. + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. - - `string` + - `"project_id"` - - `"inactive" or "enforcing"` + - `"user_id"` - Whether the hard spend limit is currently enforcing. + - `"api_key_id"` - - `"inactive"` + - `"model"` - - `"enforcing"` +- `limit: optional number` - - `interval: string or "month"` + Specifies the number of buckets to return. - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - - `string` +- `models: optional array of string` - - `"month"` + Return only usage for these models. - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +- `page: optional string` - - `"month"` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. - - `object: "organization.spend_limit"` +- `project_ids: optional array of string` - The object type, which is always `organization.spend_limit`. + Return only usage for these projects. - - `"organization.spend_limit"` +- `user_ids: optional array of string` - - `threshold_amount: number` + Return only usage for these users. - The hard spend limit amount, in cents. +### Returns -### Example +- `data: array of object { end_time, object, results, start_time }` -```http -curl https://api.openai.com/v1/organization/spend_limit \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "currency": "USD", - "interval": "month", - "threshold_amount": 1 - }' -``` + - `end_time: number` -#### Response + - `object: "bucket"` -```json -{ - "currency": "USD", - "enforcement": { - "status": "inactive" - }, - "interval": "month", - "object": "organization.spend_limit", - "threshold_amount": 0 -} -``` + - `"bucket"` -### Example + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -```http -curl -X POST https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 10000, - "currency": "USD", - "interval": "month" - }' -``` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -#### Response + The aggregated completions usage details of the specific time bucket. -```json -{ - "object": "organization.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" - } -} -``` + - `input_tokens: number` -## Delete organization spend limit + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -**delete** `/organization/spend_limit` + - `num_model_requests: number` -Delete the organization's hard spend limit. + The count of requests made to the model. -### Returns + - `object: "organization.usage.completions.result"` -- `OrganizationSpendLimitDeleted object { deleted, object }` + - `"organization.usage.completions.result"` - Confirmation payload returned after deleting an organization hard spend limit. + - `output_tokens: number` - - `deleted: boolean` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Whether the hard spend limit was deleted. + - `api_key_id: optional string` - - `object: "organization.spend_limit.deleted"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The object type, which is always `organization.spend_limit.deleted`. + - `batch: optional boolean` - - `"organization.spend_limit.deleted"` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -### Example + - `input_audio_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/spend_limit \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of uncached audio input tokens used. -#### Response + - `input_cache_write_tokens: optional number` -```json -{ - "deleted": true, - "object": "organization.spend_limit.deleted" -} -``` + The aggregated number of input tokens written to the cache. -### Example + - `input_cached_audio_tokens: optional number` -```http -curl -X DELETE https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of cached audio input tokens used. -#### Response + - `input_cached_image_tokens: optional number` -```json -{ - "object": "organization.spend_limit.deleted", - "deleted": true -} -``` + The aggregated number of cached image input tokens used. -## Domain Types + - `input_cached_text_tokens: optional number` -### Organization Spend Limit + The aggregated number of cached text input tokens used. -- `OrganizationSpendLimit object { currency, enforcement, interval, 2 more }` + - `input_cached_tokens: optional number` - Represents a hard spend limit configured at the organization level. + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `currency: string or "USD"` + - `input_image_tokens: optional number` - The currency for the threshold amount. Currently, only `USD` is supported. + The aggregated number of uncached image input tokens used. - - `string` + - `input_text_tokens: optional number` - - `"USD"` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - The currency for the threshold amount. Currently, only `USD` is supported. + - `input_uncached_tokens: optional number` - - `"USD"` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `enforcement: object { status }` + - `model: optional string` - The current enforcement state of the hard spend limit. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `status: string or "inactive" or "enforcing"` + - `output_audio_tokens: optional number` - Whether the hard spend limit is currently enforcing. + The aggregated number of audio output tokens used. - - `string` + - `output_image_tokens: optional number` - - `"inactive" or "enforcing"` + The aggregated number of image output tokens used. - Whether the hard spend limit is currently enforcing. + - `output_text_tokens: optional number` - - `"inactive"` + The aggregated number of text output tokens used. - - `"enforcing"` + - `project_id: optional string` - - `interval: string or "month"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + - `service_tier: optional string` - - `string` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `"month"` + - `user_id: optional string` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"month"` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - - `object: "organization.spend_limit"` + The aggregated embeddings usage details of the specific time bucket. - The object type, which is always `organization.spend_limit`. + - `input_tokens: number` - - `"organization.spend_limit"` + The aggregated number of input tokens used. - - `threshold_amount: number` + - `num_model_requests: number` - The hard spend limit amount, in cents. + The count of requests made to the model. -### Organization Spend Limit Deleted + - `object: "organization.usage.embeddings.result"` -- `OrganizationSpendLimitDeleted object { deleted, object }` + - `"organization.usage.embeddings.result"` - Confirmation payload returned after deleting an organization hard spend limit. + - `api_key_id: optional string` - - `deleted: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the hard spend limit was deleted. + - `model: optional string` - - `object: "organization.spend_limit.deleted"` + When `group_by=model`, this field provides the model name of the grouped usage result. - The object type, which is always `organization.spend_limit.deleted`. + - `project_id: optional string` - - `"organization.spend_limit.deleted"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -# Spend Alerts + - `user_id: optional string` -## List organization spend alerts + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -**get** `/organization/spend_alerts` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` -Lists organization spend alerts. + The aggregated moderations usage details of the specific time bucket. -### Query Parameters + - `input_tokens: number` -- `after: optional string` + The aggregated number of input tokens used. - Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page. + - `num_model_requests: number` -- `before: optional string` + The count of requests made to the model. - Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page. + - `object: "organization.usage.moderations.result"` -- `limit: optional number` + - `"organization.usage.moderations.result"` - A limit on the number of spend alerts to return. Defaults to 20. + - `api_key_id: optional string` -- `order: optional "asc" or "desc"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Sort order for the returned spend alerts. + - `model: optional string` - - `"asc"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"desc"` + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `data: array of OrganizationSpendAlert` + - `user_id: optional string` - Spend alerts returned in the current page. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - The identifier, which can be referenced in API endpoints. + The aggregated images usage details of the specific time bucket. - - `currency: "USD"` + - `images: number` - The currency for the threshold amount. + The number of images processed. - - `"USD"` + - `num_model_requests: number` - - `interval: "month"` + The count of requests made to the model. - The time interval for evaluating spend against the threshold. + - `object: "organization.usage.images.result"` - - `"month"` + - `"organization.usage.images.result"` - - `notification_channel: object { recipients, type, subject_prefix }` + - `api_key_id: optional string` - Email notification settings for a spend alert. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `recipients: array of string` + - `model: optional string` - Email addresses that receive the spend alert notification. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `type: "email"` + - `project_id: optional string` - The notification channel type. Currently only `email` is supported. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"email"` + - `size: optional string` - - `subject_prefix: optional string` + When `group_by=size`, this field provides the image size of the grouped usage result. - Optional subject prefix for alert emails. + - `source: optional string` - - `object: "organization.spend_alert"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - The object type, which is always `organization.spend_alert`. + - `user_id: optional string` - - `"organization.spend_alert"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `threshold_amount: number` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - The alert threshold amount, in cents. + The aggregated audio speeches usage details of the specific time bucket. -- `first_id: string` + - `characters: number` - The ID of the first spend alert in this page. + The number of characters processed. -- `has_more: boolean` + - `num_model_requests: number` - Whether more spend alerts are available when paginating. + The count of requests made to the model. -- `last_id: string` + - `object: "organization.usage.audio_speeches.result"` - The ID of the last spend alert in this page. + - `"organization.usage.audio_speeches.result"` -- `object: "list"` + - `api_key_id: optional string` - Always `list`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"list"` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/spend_alerts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "data": [ - { - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "organization.spend_alert", - "threshold_amount": 0 - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/spend_alerts?limit=20&order=asc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -#### Response + The aggregated audio transcriptions usage details of the specific time bucket. -```json -{ - "object": "list", - "data": [ - { - "id": "alert_abc123", - "object": "organization.spend_alert", - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } - } - ], - "first_id": "alert_abc123", - "last_id": "alert_abc123", - "has_more": false -} -``` + - `num_model_requests: number` -## Create organization spend alert + The count of requests made to the model. -**post** `/organization/spend_alerts` + - `object: "organization.usage.audio_transcriptions.result"` -Creates an organization spend alert. + - `"organization.usage.audio_transcriptions.result"` -### Body Parameters + - `seconds: number` -- `currency: "USD"` + The number of seconds processed. - The currency for the threshold amount. + - `api_key_id: optional string` - - `"USD"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `interval: "month"` + - `model: optional string` - The time interval for evaluating spend against the threshold. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"month"` + - `project_id: optional string` -- `notification_channel: object { recipients, type, subject_prefix }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Email notification settings for a spend alert. + - `user_id: optional string` - - `recipients: array of string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Email addresses that receive the spend alert notification. + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `type: "email"` + The aggregated vector stores usage details of the specific time bucket. - The notification channel type. Currently only `email` is supported. + - `object: "organization.usage.vector_stores.result"` - - `"email"` + - `"organization.usage.vector_stores.result"` - - `subject_prefix: optional string` + - `usage_bytes: number` - Optional subject prefix for alert emails. + The vector stores usage in bytes. -- `threshold_amount: number` + - `project_id: optional string` - The alert threshold amount, in cents. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -- `OrganizationSpendAlert object { id, currency, interval, 3 more }` + The aggregated code interpreter sessions usage details of the specific time bucket. - Represents a spend alert configured at the organization level. + - `num_sessions: number` - - `id: string` + The number of code interpreter sessions. - The identifier, which can be referenced in API endpoints. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `currency: "USD"` + - `"organization.usage.code_interpreter_sessions.result"` - The currency for the threshold amount. + - `project_id: optional string` - - `"USD"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `interval: "month"` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The time interval for evaluating spend against the threshold. + The aggregated file search calls usage details of the specific time bucket. - - `"month"` + - `num_requests: number` - - `notification_channel: object { recipients, type, subject_prefix }` + The count of file search calls. - Email notification settings for a spend alert. + - `object: "organization.usage.file_searches.result"` - - `recipients: array of string` + - `"organization.usage.file_searches.result"` - Email addresses that receive the spend alert notification. + - `api_key_id: optional string` - - `type: "email"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The notification channel type. Currently only `email` is supported. + - `project_id: optional string` - - `"email"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `subject_prefix: optional string` + - `user_id: optional string` - Optional subject prefix for alert emails. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `object: "organization.spend_alert"` + - `vector_store_id: optional string` - The object type, which is always `organization.spend_alert`. + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - - `"organization.spend_alert"` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `threshold_amount: number` + The aggregated web search calls usage details of the specific time bucket. - The alert threshold amount, in cents. + - `num_model_requests: number` -### Example + The count of model requests. -```http -curl https://api.openai.com/v1/organization/spend_alerts \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email" - }, - "threshold_amount": 0 - }' -``` + - `num_requests: number` -#### Response + The count of web search calls. -```json -{ - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "organization.spend_alert", - "threshold_amount": 0 -} -``` + - `object: "organization.usage.web_searches.result"` -### Example + - `"organization.usage.web_searches.result"` -```http -curl -X POST https://api.openai.com/v1/organization/spend_alerts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } - }' -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "id": "alert_abc123", - "object": "organization.spend_alert", - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } -} -``` + - `context_level: optional string` -## Retrieve organization spend alert + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -**get** `/organization/spend_alerts/{alert_id}` + - `model: optional string` -Retrieves an organization spend alert. + When `group_by=model`, this field provides the model name of the grouped usage result. -### Path Parameters + - `project_id: optional string` -- `alert_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `OrganizationSpendAlert object { id, currency, interval, 3 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Represents a spend alert configured at the organization level. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `id: string` + The aggregated costs details of the specific time bucket. - The identifier, which can be referenced in API endpoints. + - `object: "organization.costs.result"` - - `currency: "USD"` + - `"organization.costs.result"` - The currency for the threshold amount. + - `amount: optional object { currency, value }` - - `"USD"` + The monetary value in its associated currency. - - `interval: "month"` + - `currency: optional string` - The time interval for evaluating spend against the threshold. + Lowercase ISO-4217 currency e.g. "usd" - - `"month"` + - `value: optional number` - - `notification_channel: object { recipients, type, subject_prefix }` + The numeric value of the cost. - Email notification settings for a spend alert. + - `api_key_id: optional string` - - `recipients: array of string` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - Email addresses that receive the spend alert notification. + - `line_item: optional string` - - `type: "email"` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - The notification channel type. Currently only `email` is supported. + - `project_id: optional string` - - `"email"` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `subject_prefix: optional string` + - `quantity: optional number` - Optional subject prefix for alert emails. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `object: "organization.spend_alert"` + - `start_time: number` - The object type, which is always `organization.spend_alert`. +- `has_more: boolean` - - `"organization.spend_alert"` +- `next_page: string` - - `threshold_amount: number` +- `object: "page"` - The alert threshold amount, in cents. + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ +curl https://api.openai.com/v1/organization/usage/moderations \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -20202,684 +21841,547 @@ curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ ```json { - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "organization.spend_alert", - "threshold_amount": 0 + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "id": "alert_abc123", - "object": "organization.spend_alert", - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.moderations.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] } + ], + "has_more": false, + "next_page": null } ``` -## Update organization spend alert +## Vector stores -**post** `/organization/spend_alerts/{alert_id}` +**get** `/organization/usage/vector_stores` -Updates an organization spend alert. +Get vector stores usage details for the organization. -### Path Parameters +### Query Parameters -- `alert_id: string` +- `start_time: number` -### Body Parameters + Start time (Unix seconds) of the query time range, inclusive. -- `currency: "USD"` +- `bucket_width: optional "1m" or "1h" or "1d"` - The currency for the threshold amount. + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - `"USD"` + - `"1m"` -- `interval: "month"` + - `"1h"` - The time interval for evaluating spend against the threshold. + - `"1d"` - - `"month"` +- `end_time: optional number` -- `notification_channel: object { recipients, type, subject_prefix }` + End time (Unix seconds) of the query time range, exclusive. - Email notification settings for a spend alert. +- `group_by: optional array of "project_id"` - - `recipients: array of string` + Group the usage data by the specified fields. Support fields include `project_id`. - Email addresses that receive the spend alert notification. + - `"project_id"` - - `type: "email"` +- `limit: optional number` - The notification channel type. Currently only `email` is supported. + Specifies the number of buckets to return. - - `"email"` + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 - - `subject_prefix: optional string` +- `page: optional string` - Optional subject prefix for alert emails. + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. -- `threshold_amount: number` +- `project_ids: optional array of string` - The alert threshold amount, in cents. + Return only usage for these projects. ### Returns -- `OrganizationSpendAlert object { id, currency, interval, 3 more }` - - Represents a spend alert configured at the organization level. - - - `id: string` - - The identifier, which can be referenced in API endpoints. - - - `currency: "USD"` +- `data: array of object { end_time, object, results, start_time }` - The currency for the threshold amount. + - `end_time: number` - - `"USD"` + - `object: "bucket"` - - `interval: "month"` + - `"bucket"` - The time interval for evaluating spend against the threshold. + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `"month"` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - - `notification_channel: object { recipients, type, subject_prefix }` + The aggregated completions usage details of the specific time bucket. - Email notification settings for a spend alert. + - `input_tokens: number` - - `recipients: array of string` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Email addresses that receive the spend alert notification. + - `num_model_requests: number` - - `type: "email"` + The count of requests made to the model. - The notification channel type. Currently only `email` is supported. + - `object: "organization.usage.completions.result"` - - `"email"` + - `"organization.usage.completions.result"` - - `subject_prefix: optional string` + - `output_tokens: number` - Optional subject prefix for alert emails. + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `object: "organization.spend_alert"` + - `api_key_id: optional string` - The object type, which is always `organization.spend_alert`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"organization.spend_alert"` + - `batch: optional boolean` - - `threshold_amount: number` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - The alert threshold amount, in cents. + - `input_audio_tokens: optional number` -### Example + The aggregated number of uncached audio input tokens used. -```http -curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email" - }, - "threshold_amount": 0 - }' -``` + - `input_cache_write_tokens: optional number` -#### Response + The aggregated number of input tokens written to the cache. -```json -{ - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "organization.spend_alert", - "threshold_amount": 0 -} -``` + - `input_cached_audio_tokens: optional number` -### Example + The aggregated number of cached audio input tokens used. -```http -curl -X POST https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } - }' -``` + - `input_cached_image_tokens: optional number` -#### Response + The aggregated number of cached image input tokens used. -```json -{ - "id": "alert_abc123", - "object": "organization.spend_alert", - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } -} -``` + - `input_cached_text_tokens: optional number` -## Delete organization spend alert + The aggregated number of cached text input tokens used. -**delete** `/organization/spend_alerts/{alert_id}` + - `input_cached_tokens: optional number` -Deletes an organization spend alert. + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Path Parameters + - `input_image_tokens: optional number` -- `alert_id: string` + The aggregated number of uncached image input tokens used. -### Returns + - `input_text_tokens: optional number` -- `OrganizationSpendAlertDeleted object { id, deleted, object }` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - Confirmation payload returned after deleting an organization spend alert. + - `input_uncached_tokens: optional number` - - `id: string` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - The deleted spend alert ID. + - `model: optional string` - - `deleted: boolean` + When `group_by=model`, this field provides the model name of the grouped usage result. - Whether the spend alert was deleted. + - `output_audio_tokens: optional number` - - `object: "organization.spend_alert.deleted"` + The aggregated number of audio output tokens used. - Always `organization.spend_alert.deleted`. + - `output_image_tokens: optional number` - - `"organization.spend_alert.deleted"` + The aggregated number of image output tokens used. -### Example + - `output_text_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/spend_alerts/$ALERT_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of text output tokens used. -#### Response + - `project_id: optional string` -```json -{ - "id": "id", - "deleted": true, - "object": "organization.spend_alert.deleted" -} -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Example + - `service_tier: optional string` -```http -curl -X DELETE https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "id": "alert_abc123", - "object": "organization.spend_alert.deleted", - "deleted": true -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -## Domain Types + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -### Organization Spend Alert + The aggregated embeddings usage details of the specific time bucket. -- `OrganizationSpendAlert object { id, currency, interval, 3 more }` + - `input_tokens: number` - Represents a spend alert configured at the organization level. + The aggregated number of input tokens used. - - `id: string` + - `num_model_requests: number` - The identifier, which can be referenced in API endpoints. + The count of requests made to the model. - - `currency: "USD"` + - `object: "organization.usage.embeddings.result"` - The currency for the threshold amount. + - `"organization.usage.embeddings.result"` - - `"USD"` + - `api_key_id: optional string` - - `interval: "month"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The time interval for evaluating spend against the threshold. + - `model: optional string` - - `"month"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `notification_channel: object { recipients, type, subject_prefix }` + - `project_id: optional string` - Email notification settings for a spend alert. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `recipients: array of string` + - `user_id: optional string` - Email addresses that receive the spend alert notification. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `type: "email"` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - The notification channel type. Currently only `email` is supported. + The aggregated moderations usage details of the specific time bucket. - - `"email"` + - `input_tokens: number` - - `subject_prefix: optional string` + The aggregated number of input tokens used. - Optional subject prefix for alert emails. + - `num_model_requests: number` - - `object: "organization.spend_alert"` + The count of requests made to the model. - The object type, which is always `organization.spend_alert`. + - `object: "organization.usage.moderations.result"` - - `"organization.spend_alert"` + - `"organization.usage.moderations.result"` - - `threshold_amount: number` + - `api_key_id: optional string` - The alert threshold amount, in cents. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Organization Spend Alert Deleted + - `model: optional string` -- `OrganizationSpendAlertDeleted object { id, deleted, object }` + When `group_by=model`, this field provides the model name of the grouped usage result. - Confirmation payload returned after deleting an organization spend alert. + - `project_id: optional string` - - `id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The deleted spend alert ID. + - `user_id: optional string` - - `deleted: boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Whether the spend alert was deleted. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `object: "organization.spend_alert.deleted"` + The aggregated images usage details of the specific time bucket. - Always `organization.spend_alert.deleted`. + - `images: number` - - `"organization.spend_alert.deleted"` + The number of images processed. -# Certificates + - `num_model_requests: number` -## List organization certificates + The count of requests made to the model. -**get** `/organization/certificates` + - `object: "organization.usage.images.result"` -List uploaded certificates for this organization. + - `"organization.usage.images.result"` -### Query Parameters + - `api_key_id: optional string` -- `after: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `model: optional string` -- `limit: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `project_id: optional string` -- `order: optional "asc" or "desc"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `size: optional string` - - `"asc"` + When `group_by=size`, this field provides the image size of the grouped usage result. - - `"desc"` + - `source: optional string` -### Returns + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -- `data: array of object { id, active, certificate_details, 3 more }` + - `user_id: optional string` - - `id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `active: boolean` + The aggregated audio speeches usage details of the specific time bucket. - Whether the certificate is currently active at the organization level. + - `characters: number` - - `certificate_details: object { expires_at, valid_at }` + The number of characters processed. - - `expires_at: optional number` + - `num_model_requests: number` - The Unix timestamp (in seconds) of when the certificate expires. + The count of requests made to the model. - - `valid_at: optional number` + - `object: "organization.usage.audio_speeches.result"` - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `"organization.usage.audio_speeches.result"` - - `created_at: number` + - `api_key_id: optional string` - The Unix timestamp (in seconds) of when the certificate was uploaded. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `name: string` + - `model: optional string` - The name of the certificate. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `object: "organization.certificate"` + - `project_id: optional string` - The object type, which is always `organization.certificate`. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"organization.certificate"` + - `user_id: optional string` -- `first_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `has_more: boolean` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -- `last_id: string` + The aggregated audio transcriptions usage details of the specific time bucket. -- `object: "list"` + - `num_model_requests: number` - - `"list"` + The count of requests made to the model. -### Example + - `object: "organization.usage.audio_transcriptions.result"` -```http -curl https://api.openai.com/v1/organization/certificates \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.usage.audio_transcriptions.result"` -#### Response + - `seconds: number` -```json -{ - "data": [ - { - "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "organization.certificate" - } - ], - "first_id": "cert_abc", - "has_more": true, - "last_id": "cert_abc", - "object": "list" -} -``` + The number of seconds processed. -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/certificates \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "object": "list", - "data": [ - { - "object": "organization.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - ], - "first_id": "cert_abc", - "last_id": "cert_abc", - "has_more": false -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -## Upload certificate + - `project_id: optional string` -**post** `/organization/certificates` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -Upload a certificate to the organization. This does **not** automatically activate the certificate. + - `user_id: optional string` -Organizations can upload up to 50 certificates. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Body Parameters + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -- `certificate: string` + The aggregated vector stores usage details of the specific time bucket. - The certificate content in PEM format + - `object: "organization.usage.vector_stores.result"` -- `name: optional string` + - `"organization.usage.vector_stores.result"` - An optional name for the certificate + - `usage_bytes: number` -### Returns + The vector stores usage in bytes. -- `Certificate object { id, certificate_details, created_at, 3 more }` + - `project_id: optional string` - Represents an individual `certificate` uploaded to the organization. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - The identifier, which can be referenced in API endpoints + The aggregated code interpreter sessions usage details of the specific time bucket. - - `certificate_details: object { content, expires_at, valid_at }` + - `num_sessions: number` - - `content: optional string` + The number of code interpreter sessions. - The content of the certificate in PEM format. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `expires_at: optional number` + - `"organization.usage.code_interpreter_sessions.result"` - The Unix timestamp (in seconds) of when the certificate expires. + - `project_id: optional string` - - `valid_at: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `created_at: number` + The aggregated file search calls usage details of the specific time bucket. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `num_requests: number` - - `name: string` + The count of file search calls. - The name of the certificate. + - `object: "organization.usage.file_searches.result"` - - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` + - `"organization.usage.file_searches.result"` - The object type. + - `api_key_id: optional string` - - If creating, updating, or getting a specific certificate, the object type is `certificate`. - - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. - - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"certificate"` + - `project_id: optional string` - - `"organization.certificate"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"organization.project.certificate"` + - `user_id: optional string` - - `active: optional boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. + - `vector_store_id: optional string` -### Example + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/certificates \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "certificate": "certificate" - }' -``` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -#### Response + The aggregated web search calls usage details of the specific time bucket. -```json -{ - "id": "id", - "certificate_details": { - "content": "content", - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "certificate", - "active": true -} -``` + - `num_model_requests: number` -### Example + The count of model requests. -```http -curl -X POST https://api.openai.com/v1/organization/certificates \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "name": "My Example Certificate", - "certificate": "-----BEGIN CERTIFICATE-----\\nMIIDeT...\\n-----END CERTIFICATE-----" -}' -``` + - `num_requests: number` -#### Response + The count of web search calls. -```json -{ - "object": "certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } -} -``` + - `object: "organization.usage.web_searches.result"` -## Get certificate + - `"organization.usage.web_searches.result"` -**get** `/organization/certificates/{certificate_id}` + - `api_key_id: optional string` -Get a certificate that has been uploaded to the organization. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -You can get a certificate regardless of whether it is active or not. + - `context_level: optional string` -### Path Parameters + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `certificate_id: string` + - `model: optional string` -### Query Parameters + When `group_by=model`, this field provides the model name of the grouped usage result. -- `include: optional array of "content"` + - `project_id: optional string` - A list of additional fields to include in the response. Currently the only supported value is `content` to fetch the PEM content of the certificate. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"content"` + - `user_id: optional string` -### Returns + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `Certificate object { id, certificate_details, created_at, 3 more }` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - Represents an individual `certificate` uploaded to the organization. + The aggregated costs details of the specific time bucket. - - `id: string` + - `object: "organization.costs.result"` - The identifier, which can be referenced in API endpoints + - `"organization.costs.result"` - - `certificate_details: object { content, expires_at, valid_at }` + - `amount: optional object { currency, value }` - - `content: optional string` + The monetary value in its associated currency. - The content of the certificate in PEM format. + - `currency: optional string` - - `expires_at: optional number` + Lowercase ISO-4217 currency e.g. "usd" - The Unix timestamp (in seconds) of when the certificate expires. + - `value: optional number` - - `valid_at: optional number` + The numeric value of the cost. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `api_key_id: optional string` - - `created_at: number` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `line_item: optional string` - - `name: string` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - The name of the certificate. + - `project_id: optional string` - - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - The object type. + - `quantity: optional number` - - If creating, updating, or getting a specific certificate, the object type is `certificate`. - - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. - - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `"certificate"` + - `start_time: number` - - `"organization.certificate"` +- `has_more: boolean` - - `"organization.project.certificate"` +- `next_page: string` - - `active: optional boolean` +- `object: "page"` - Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ +curl https://api.openai.com/v1/organization/usage/vector_stores \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -20887,729 +22389,573 @@ curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ ```json { - "id": "id", - "certificate_details": { - "content": "content", - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "certificate", - "active": true + "data": [ + { + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 + } + ], + "has_more": true, + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl "https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content" \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" +curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "created_at": 1234567, - "certificate_details": { - "valid_at": 1234567, - "expires_at": 12345678, - "content": "-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----" + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": null + } + ] } + ], + "has_more": false, + "next_page": null } ``` -## Modify certificate - -**post** `/organization/certificates/{certificate_id}` - -Modify a certificate. Note that only the name can be modified. - -### Path Parameters - -- `certificate_id: string` - -### Body Parameters - -- `name: optional string` - - The updated name for the certificate - -### Returns +## Web search calls -- `Certificate object { id, certificate_details, created_at, 3 more }` +**get** `/organization/usage/web_search_calls` - Represents an individual `certificate` uploaded to the organization. +Get web search calls usage details for the organization. - - `id: string` +### Query Parameters - The identifier, which can be referenced in API endpoints +- `start_time: number` - - `certificate_details: object { content, expires_at, valid_at }` + Start time (Unix seconds) of the query time range, inclusive. - - `content: optional string` +- `api_key_ids: optional array of string` - The content of the certificate in PEM format. + Return only usage for these API keys. - - `expires_at: optional number` +- `bucket_width: optional "1m" or "1h" or "1d"` - The Unix timestamp (in seconds) of when the certificate expires. + Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. - - `valid_at: optional number` + - `"1m"` - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `"1h"` - - `created_at: number` + - `"1d"` - The Unix timestamp (in seconds) of when the certificate was uploaded. +- `context_levels: optional array of "low" or "medium" or "high"` - - `name: string` + Return only web search usage for these context levels. - The name of the certificate. + - `"low"` - - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` + - `"medium"` - The object type. + - `"high"` - - If creating, updating, or getting a specific certificate, the object type is `certificate`. - - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. - - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. +- `end_time: optional number` - - `"certificate"` + End time (Unix seconds) of the query time range, exclusive. - - `"organization.certificate"` +- `group_by: optional array of "project_id" or "user_id" or "api_key_id" or 2 more` - - `"organization.project.certificate"` + Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `context_level` or any combination of them. - - `active: optional boolean` + - `"project_id"` - Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. + - `"user_id"` -### Example + - `"api_key_id"` -```http -curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + - `"model"` -#### Response + - `"context_level"` -```json -{ - "id": "id", - "certificate_details": { - "content": "content", - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "certificate", - "active": true -} -``` +- `limit: optional number` -### Example + Specifies the number of buckets to return. -```http -curl -X POST https://api.openai.com/v1/organization/certificates/cert_abc \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "name": "Renamed Certificate" -}' -``` + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 -#### Response +- `models: optional array of string` -```json -{ - "object": "certificate", - "id": "cert_abc", - "name": "Renamed Certificate", - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } -} -``` + Return only usage for these models. -## Delete certificate +- `page: optional string` -**delete** `/organization/certificates/{certificate_id}` + A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. -Delete a certificate from the organization. +- `project_ids: optional array of string` -The certificate must be inactive for the organization and all projects. + Return only usage for these projects. -### Path Parameters +- `user_ids: optional array of string` -- `certificate_id: string` + Return only usage for these users. ### Returns -- `id: string` +- `data: array of object { end_time, object, results, start_time }` - The ID of the certificate that was deleted. + - `end_time: number` -- `object: "certificate.deleted"` + - `object: "bucket"` - The object type, must be `certificate.deleted`. + - `"bucket"` - - `"certificate.deleted"` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -### Example + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -```http -curl https://api.openai.com/v1/organization/certificates/$CERTIFICATE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated completions usage details of the specific time bucket. -#### Response + - `input_tokens: number` -```json -{ - "id": "id", - "object": "certificate.deleted" -} -``` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Example + - `num_model_requests: number` -```http -curl -X DELETE https://api.openai.com/v1/organization/certificates/cert_abc \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.completions.result"` -```json -{ - "object": "certificate.deleted", - "id": "cert_abc" -} -``` + - `"organization.usage.completions.result"` -## Activate certificates for organization + - `output_tokens: number` -**post** `/organization/certificates/activate` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -Activate certificates at the organization level. + - `api_key_id: optional string` -You can atomically and idempotently activate up to 10 certificates at a time. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Body Parameters + - `batch: optional boolean` -- `certificate_ids: array of string` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -### Returns + - `input_audio_tokens: optional number` -- `data: array of object { id, active, certificate_details, 3 more }` + The aggregated number of uncached audio input tokens used. - - `id: string` + - `input_cache_write_tokens: optional number` - The identifier, which can be referenced in API endpoints + The aggregated number of input tokens written to the cache. - - `active: boolean` + - `input_cached_audio_tokens: optional number` - Whether the certificate is currently active at the organization level. + The aggregated number of cached audio input tokens used. - - `certificate_details: object { expires_at, valid_at }` + - `input_cached_image_tokens: optional number` - - `expires_at: optional number` + The aggregated number of cached image input tokens used. - The Unix timestamp (in seconds) of when the certificate expires. + - `input_cached_text_tokens: optional number` - - `valid_at: optional number` + The aggregated number of cached text input tokens used. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `input_cached_tokens: optional number` - - `created_at: number` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `input_image_tokens: optional number` - - `name: string` + The aggregated number of uncached image input tokens used. - The name of the certificate. + - `input_text_tokens: optional number` - - `object: "organization.certificate"` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - The object type, which is always `organization.certificate`. + - `input_uncached_tokens: optional number` - - `"organization.certificate"` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. -- `object: "organization.certificate.activation"` + - `model: optional string` - The organization certificate activation result type. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"organization.certificate.activation"` + - `output_audio_tokens: optional number` -### Example + The aggregated number of audio output tokens used. -```http -curl https://api.openai.com/v1/organization/certificates/activate \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "certificate_ids": [ - "cert_abc" - ] - }' -``` + - `output_image_tokens: optional number` -#### Response + The aggregated number of image output tokens used. -```json -{ - "data": [ - { - "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "organization.certificate" - } - ], - "object": "organization.certificate.activation" -} -``` + - `output_text_tokens: optional number` -### Example + The aggregated number of text output tokens used. -```http -curl https://api.openai.com/v1/organization/certificates/activate \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "certificate_ids": ["cert_abc", "cert_def"] -}' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "object": "organization.certificate.activation", - "data": [ - { - "object": "organization.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - { - "object": "organization.certificate", - "id": "cert_def", - "name": "My Example Certificate 2", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - ], -} -``` + - `service_tier: optional string` -## Deactivate certificates for organization + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -**post** `/organization/certificates/deactivate` + - `user_id: optional string` -Deactivate certificates at the organization level. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -You can atomically and idempotently deactivate up to 10 certificates at a time. + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -### Body Parameters + The aggregated embeddings usage details of the specific time bucket. -- `certificate_ids: array of string` + - `input_tokens: number` -### Returns + The aggregated number of input tokens used. -- `data: array of object { id, active, certificate_details, 3 more }` + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - The identifier, which can be referenced in API endpoints + - `object: "organization.usage.embeddings.result"` - - `active: boolean` + - `"organization.usage.embeddings.result"` - Whether the certificate is currently active at the organization level. + - `api_key_id: optional string` - - `certificate_details: object { expires_at, valid_at }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `expires_at: optional number` + - `model: optional string` - The Unix timestamp (in seconds) of when the certificate expires. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `valid_at: optional number` + - `project_id: optional string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `created_at: number` + - `user_id: optional string` - The Unix timestamp (in seconds) of when the certificate was uploaded. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `name: string` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - The name of the certificate. + The aggregated moderations usage details of the specific time bucket. - - `object: "organization.certificate"` + - `input_tokens: number` - The object type, which is always `organization.certificate`. + The aggregated number of input tokens used. - - `"organization.certificate"` + - `num_model_requests: number` -- `object: "organization.certificate.deactivation"` + The count of requests made to the model. - The organization certificate deactivation result type. + - `object: "organization.usage.moderations.result"` - - `"organization.certificate.deactivation"` + - `"organization.usage.moderations.result"` -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/certificates/deactivate \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "certificate_ids": [ - "cert_abc" - ] - }' -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "data": [ - { - "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "organization.certificate" - } - ], - "object": "organization.certificate.deactivation" -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/organization/certificates/deactivate \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "certificate_ids": ["cert_abc", "cert_def"] -}' -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "object": "organization.certificate.deactivation", - "data": [ - { - "object": "organization.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": false, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - { - "object": "organization.certificate", - "id": "cert_def", - "name": "My Example Certificate 2", - "active": false, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - ], -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -## Domain Types + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -### Certificate + The aggregated images usage details of the specific time bucket. -- `Certificate object { id, certificate_details, created_at, 3 more }` + - `images: number` - Represents an individual `certificate` uploaded to the organization. + The number of images processed. - - `id: string` + - `num_model_requests: number` - The identifier, which can be referenced in API endpoints + The count of requests made to the model. - - `certificate_details: object { content, expires_at, valid_at }` + - `object: "organization.usage.images.result"` - - `content: optional string` + - `"organization.usage.images.result"` - The content of the certificate in PEM format. + - `api_key_id: optional string` - - `expires_at: optional number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate expires. + - `model: optional string` - - `valid_at: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `project_id: optional string` - - `created_at: number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `size: optional string` - - `name: string` + When `group_by=size`, this field provides the image size of the grouped usage result. - The name of the certificate. + - `source: optional string` - - `object: "certificate" or "organization.certificate" or "organization.project.certificate"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - The object type. + - `user_id: optional string` - - If creating, updating, or getting a specific certificate, the object type is `certificate`. - - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. - - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"certificate"` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `"organization.certificate"` + The aggregated audio speeches usage details of the specific time bucket. - - `"organization.project.certificate"` + - `characters: number` - - `active: optional boolean` + The number of characters processed. - Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. + - `num_model_requests: number` -### Certificate List Response + The count of requests made to the model. -- `CertificateListResponse object { id, active, certificate_details, 3 more }` + - `object: "organization.usage.audio_speeches.result"` - Represents an individual certificate configured at the organization level. + - `"organization.usage.audio_speeches.result"` - - `id: string` + - `api_key_id: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `active: boolean` + - `model: optional string` - Whether the certificate is currently active at the organization level. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `certificate_details: object { expires_at, valid_at }` + - `project_id: optional string` - - `expires_at: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate expires. + - `user_id: optional string` - - `valid_at: optional number` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `created_at: number` + The aggregated audio transcriptions usage details of the specific time bucket. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `num_model_requests: number` - - `name: string` + The count of requests made to the model. - The name of the certificate. + - `object: "organization.usage.audio_transcriptions.result"` - - `object: "organization.certificate"` + - `"organization.usage.audio_transcriptions.result"` - The object type, which is always `organization.certificate`. + - `seconds: number` - - `"organization.certificate"` + The number of seconds processed. -### Certificate Delete Response + - `api_key_id: optional string` -- `CertificateDeleteResponse object { id, object }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `id: string` + - `model: optional string` - The ID of the certificate that was deleted. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `object: "certificate.deleted"` + - `project_id: optional string` - The object type, must be `certificate.deleted`. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"certificate.deleted"` + - `user_id: optional string` -### Certificate Activate Response + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `CertificateActivateResponse object { id, active, certificate_details, 3 more }` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - Represents an individual certificate configured at the organization level. + The aggregated vector stores usage details of the specific time bucket. - - `id: string` + - `object: "organization.usage.vector_stores.result"` - The identifier, which can be referenced in API endpoints + - `"organization.usage.vector_stores.result"` - - `active: boolean` + - `usage_bytes: number` - Whether the certificate is currently active at the organization level. + The vector stores usage in bytes. - - `certificate_details: object { expires_at, valid_at }` + - `project_id: optional string` - - `expires_at: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the certificate expires. + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - - `valid_at: optional number` + The aggregated code interpreter sessions usage details of the specific time bucket. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `num_sessions: number` - - `created_at: number` + The number of code interpreter sessions. - The Unix timestamp (in seconds) of when the certificate was uploaded. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `name: string` + - `"organization.usage.code_interpreter_sessions.result"` - The name of the certificate. + - `project_id: optional string` - - `object: "organization.certificate"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The object type, which is always `organization.certificate`. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `"organization.certificate"` + The aggregated file search calls usage details of the specific time bucket. -### Certificate Deactivate Response + - `num_requests: number` -- `CertificateDeactivateResponse object { id, active, certificate_details, 3 more }` + The count of file search calls. - Represents an individual certificate configured at the organization level. + - `object: "organization.usage.file_searches.result"` - - `id: string` + - `"organization.usage.file_searches.result"` - The identifier, which can be referenced in API endpoints + - `api_key_id: optional string` - - `active: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the certificate is currently active at the organization level. + - `project_id: optional string` - - `certificate_details: object { expires_at, valid_at }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `expires_at: optional number` + - `user_id: optional string` - The Unix timestamp (in seconds) of when the certificate expires. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `valid_at: optional number` + - `vector_store_id: optional string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - - `created_at: number` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - The Unix timestamp (in seconds) of when the certificate was uploaded. + The aggregated web search calls usage details of the specific time bucket. - - `name: string` + - `num_model_requests: number` - The name of the certificate. + The count of model requests. - - `object: "organization.certificate"` + - `num_requests: number` - The object type, which is always `organization.certificate`. + The count of web search calls. - - `"organization.certificate"` + - `object: "organization.usage.web_searches.result"` -# Projects + - `"organization.usage.web_searches.result"` -## List projects + - `api_key_id: optional string` -**get** `/organization/projects` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Returns a list of projects. + - `context_level: optional string` -### Query Parameters + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `after: optional string` + - `model: optional string` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `include_archived: optional boolean` + - `project_id: optional string` - If `true` returns all projects including those that have been `archived`. Archived projects are not included by default. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `limit: optional number` + - `user_id: optional string` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Returns + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` -- `data: array of Project` + The aggregated costs details of the specific time bucket. - - `id: string` + - `object: "organization.costs.result"` + + - `"organization.costs.result"` + + - `amount: optional object { currency, value }` - The identifier, which can be referenced in API endpoints + The monetary value in its associated currency. - - `created_at: number` + - `currency: optional string` - The Unix timestamp (in seconds) of when the project was created. + Lowercase ISO-4217 currency e.g. "usd" - - `object: "organization.project"` + - `value: optional number` - The object type, which is always `organization.project` + The numeric value of the cost. - - `"organization.project"` + - `api_key_id: optional string` - - `archived_at: optional number` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - The Unix timestamp (in seconds) of when the project was archived or `null`. + - `line_item: optional string` - - `external_key_id: optional string` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - The external key associated with the project. + - `project_id: optional string` - - `name: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - The name of the project. This appears in reporting. + - `quantity: optional number` - - `status: optional string` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - `active` or `archived` + - `start_time: number` - `has_more: boolean` -- `object: "list"` - - - `"list"` +- `next_page: string` -- `first_id: optional string` +- `object: "page"` -- `last_id: optional string` + - `"page"` ### Example ```http -curl https://api.openai.com/v1/organization/projects \ +curl https://api.openai.com/v1/organization/usage/web_search_calls \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -21619,6118 +22965,4685 @@ curl https://api.openai.com/v1/organization/projects \ { "data": [ { - "id": "id", - "created_at": 0, - "object": "organization.project", - "archived_at": 0, - "external_key_id": "external_key_id", - "name": "name", - "status": "status" + "end_time": 0, + "object": "bucket", + "results": [ + { + "input_tokens": 0, + "num_model_requests": 0, + "object": "organization.usage.completions.result", + "output_tokens": 0, + "api_key_id": "api_key_id", + "batch": true, + "input_audio_tokens": 0, + "input_cache_write_tokens": 0, + "input_cached_audio_tokens": 0, + "input_cached_image_tokens": 0, + "input_cached_text_tokens": 0, + "input_cached_tokens": 0, + "input_image_tokens": 0, + "input_text_tokens": 0, + "input_uncached_tokens": 0, + "model": "model", + "output_audio_tokens": 0, + "output_image_tokens": 0, + "output_text_tokens": 0, + "project_id": "project_id", + "service_tier": "service_tier", + "user_id": "user_id" + } + ], + "start_time": 0 } ], "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" + "next_page": "next_page", + "object": "page" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" +curl "https://api.openai.com/v1/organization/usage/web_search_calls?start_time=1730419200&limit=1" \ +-H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ +-H "Content-Type: application/json" ``` #### Response ```json { - "object": "list", + "object": "page", "data": [ { - "id": "proj_abc", - "object": "organization.project", - "name": "Project example", - "created_at": 1711471533, - "archived_at": null, - "status": "active" + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.usage.web_searches.result", + "num_model_requests": 2, + "num_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null, + "context_level": null + } + ] } ], - "first_id": "proj-abc", - "last_id": "proj-xyz", - "has_more": false + "has_more": false, + "next_page": null } ``` -## Create project +## Domain Types -**post** `/organization/projects` +### Usage Audio Speeches Response -Create a new project in the organization. Projects can be created and archived, but cannot be deleted. +- `UsageAudioSpeechesResponse object { data, has_more, next_page, object }` -### Body Parameters + - `data: array of object { end_time, object, results, start_time }` -- `name: string` + - `end_time: number` - The friendly name of the project, this name appears in reports. + - `object: "bucket"` -- `external_key_id: optional string` + - `"bucket"` - External key ID to associate with the project. + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -- `geography: optional string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - Create the project with the specified data residency region. Your organization must have access to Data residency functionality in order to use. See [data residency controls](/docs/guides/your-data#data-residency-controls) to review the functionality and limitations of setting this field. + The aggregated completions usage details of the specific time bucket. -### Returns + - `input_tokens: number` -- `Project object { id, created_at, object, 4 more }` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Represents an individual project. + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - The identifier, which can be referenced in API endpoints + - `object: "organization.usage.completions.result"` - - `created_at: number` + - `"organization.usage.completions.result"` - The Unix timestamp (in seconds) of when the project was created. + - `output_tokens: number` - - `object: "organization.project"` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The object type, which is always `organization.project` + - `api_key_id: optional string` - - `"organization.project"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `archived_at: optional number` + - `batch: optional boolean` - The Unix timestamp (in seconds) of when the project was archived or `null`. + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - - `external_key_id: optional string` + - `input_audio_tokens: optional number` - The external key associated with the project. + The aggregated number of uncached audio input tokens used. - - `name: optional string` + - `input_cache_write_tokens: optional number` - The name of the project. This appears in reporting. + The aggregated number of input tokens written to the cache. - - `status: optional string` + - `input_cached_audio_tokens: optional number` - `active` or `archived` + The aggregated number of cached audio input tokens used. -### Example + - `input_cached_image_tokens: optional number` + + The aggregated number of cached image input tokens used. + + - `input_cached_text_tokens: optional number` + + The aggregated number of cached text input tokens used. + + - `input_cached_tokens: optional number` + + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. + + - `input_image_tokens: optional number` + + The aggregated number of uncached image input tokens used. + + - `input_text_tokens: optional number` + + The aggregated number of uncached text input tokens used, excluding cache-write tokens. + + - `input_uncached_tokens: optional number` + + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. + + - `model: optional string` + + When `group_by=model`, this field provides the model name of the grouped usage result. + + - `output_audio_tokens: optional number` + + The aggregated number of audio output tokens used. + + - `output_image_tokens: optional number` + + The aggregated number of image output tokens used. + + - `output_text_tokens: optional number` + + The aggregated number of text output tokens used. + + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. + + - `service_tier: optional string` + + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. + + - `user_id: optional string` + + When `group_by=user_id`, this field provides the user ID of the grouped usage result. + + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` + + The aggregated embeddings usage details of the specific time bucket. + + - `input_tokens: number` + + The aggregated number of input tokens used. + + - `num_model_requests: number` + + The count of requests made to the model. + + - `object: "organization.usage.embeddings.result"` + + - `"organization.usage.embeddings.result"` + + - `api_key_id: optional string` + + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + + - `model: optional string` + + When `group_by=model`, this field provides the model name of the grouped usage result. + + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. + + - `user_id: optional string` + + When `group_by=user_id`, this field provides the user ID of the grouped usage result. + + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + + The aggregated moderations usage details of the specific time bucket. -```http -curl https://api.openai.com/v1/organization/projects \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "name": "name" - }' -``` + - `input_tokens: number` -#### Response + The aggregated number of input tokens used. -```json -{ - "id": "id", - "created_at": 0, - "object": "organization.project", - "archived_at": 0, - "external_key_id": "external_key_id", - "name": "name", - "status": "status" -} -``` + - `num_model_requests: number` -### Example + The count of requests made to the model. -```http -curl -X POST https://api.openai.com/v1/organization/projects \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Project ABC" - }' -``` + - `object: "organization.usage.moderations.result"` -#### Response + - `"organization.usage.moderations.result"` -```json -{ - "id": "proj_abc", - "object": "organization.project", - "name": "Project ABC", - "created_at": 1711471533, - "archived_at": null, - "status": "active" -} -``` + - `api_key_id: optional string` -## Retrieve project + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -**get** `/organization/projects/{project_id}` + - `model: optional string` -Retrieves a project. + When `group_by=model`, this field provides the model name of the grouped usage result. -### Path Parameters + - `project_id: optional string` -- `project_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `Project object { id, created_at, object, 4 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Represents an individual project. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `id: string` + The aggregated images usage details of the specific time bucket. - The identifier, which can be referenced in API endpoints + - `images: number` - - `created_at: number` + The number of images processed. - The Unix timestamp (in seconds) of when the project was created. + - `num_model_requests: number` - - `object: "organization.project"` + The count of requests made to the model. - The object type, which is always `organization.project` + - `object: "organization.usage.images.result"` - - `"organization.project"` + - `"organization.usage.images.result"` - - `archived_at: optional number` + - `api_key_id: optional string` - The Unix timestamp (in seconds) of when the project was archived or `null`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `external_key_id: optional string` + - `model: optional string` - The external key associated with the project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `name: optional string` + - `project_id: optional string` - The name of the project. This appears in reporting. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `status: optional string` + - `size: optional string` - `active` or `archived` + When `group_by=size`, this field provides the image size of the grouped usage result. -### Example + - `source: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -#### Response + - `user_id: optional string` -```json -{ - "id": "id", - "created_at": 0, - "object": "organization.project", - "archived_at": 0, - "external_key_id": "external_key_id", - "name": "name", - "status": "status" -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated audio speeches usage details of the specific time bucket. -#### Response + - `characters: number` -```json -{ - "id": "proj_abc", - "object": "organization.project", - "name": "Project example", - "created_at": 1711471533, - "archived_at": null, - "status": "active" -} -``` + The number of characters processed. -## Modify project + - `num_model_requests: number` -**post** `/organization/projects/{project_id}` + The count of requests made to the model. -Modifies a project in the organization. + - `object: "organization.usage.audio_speeches.result"` -### Path Parameters + - `"organization.usage.audio_speeches.result"` -- `project_id: string` + - `api_key_id: optional string` -### Body Parameters + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `external_key_id: optional string` + - `model: optional string` - External key ID to associate with the project. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `geography: optional string` + - `project_id: optional string` - Geography for the project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `name: optional string` + - `user_id: optional string` - The updated name of the project, this name appears in reports. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Returns + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -- `Project object { id, created_at, object, 4 more }` + The aggregated audio transcriptions usage details of the specific time bucket. - Represents an individual project. + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - The identifier, which can be referenced in API endpoints + - `object: "organization.usage.audio_transcriptions.result"` - - `created_at: number` + - `"organization.usage.audio_transcriptions.result"` - The Unix timestamp (in seconds) of when the project was created. + - `seconds: number` - - `object: "organization.project"` + The number of seconds processed. - The object type, which is always `organization.project` + - `api_key_id: optional string` - - `"organization.project"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `archived_at: optional number` + - `model: optional string` - The Unix timestamp (in seconds) of when the project was archived or `null`. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `external_key_id: optional string` + - `project_id: optional string` - The external key associated with the project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: optional string` + - `user_id: optional string` - The name of the project. This appears in reporting. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `status: optional string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - `active` or `archived` + The aggregated vector stores usage details of the specific time bucket. -### Example + - `object: "organization.usage.vector_stores.result"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + - `"organization.usage.vector_stores.result"` -#### Response + - `usage_bytes: number` -```json -{ - "id": "id", - "created_at": 0, - "object": "organization.project", - "archived_at": 0, - "external_key_id": "external_key_id", - "name": "name", - "status": "status" -} -``` + The vector stores usage in bytes. -### Example + - `project_id: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Project DEF" - }' -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -## Archive project + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -**post** `/organization/projects/{project_id}/archive` + The aggregated code interpreter sessions usage details of the specific time bucket. -Archives a project in the organization. Archived projects cannot be used or updated. + - `num_sessions: number` -### Path Parameters + The number of code interpreter sessions. -- `project_id: string` + - `object: "organization.usage.code_interpreter_sessions.result"` -### Returns + - `"organization.usage.code_interpreter_sessions.result"` -- `Project object { id, created_at, object, 4 more }` + - `project_id: optional string` - Represents an individual project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The identifier, which can be referenced in API endpoints + The aggregated file search calls usage details of the specific time bucket. - - `created_at: number` + - `num_requests: number` - The Unix timestamp (in seconds) of when the project was created. + The count of file search calls. - - `object: "organization.project"` + - `object: "organization.usage.file_searches.result"` - The object type, which is always `organization.project` + - `"organization.usage.file_searches.result"` - - `"organization.project"` + - `api_key_id: optional string` - - `archived_at: optional number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The Unix timestamp (in seconds) of when the project was archived or `null`. + - `project_id: optional string` - - `external_key_id: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The external key associated with the project. + - `user_id: optional string` - - `name: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The name of the project. This appears in reporting. + - `vector_store_id: optional string` - - `status: optional string` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - `active` or `archived` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -### Example + The aggregated web search calls usage details of the specific time bucket. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/archive \ - -X POST \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `num_model_requests: number` -#### Response + The count of model requests. -```json -{ - "id": "id", - "created_at": 0, - "object": "organization.project", - "archived_at": 0, - "external_key_id": "external_key_id", - "name": "name", - "status": "status" -} -``` + - `num_requests: number` -### Example + The count of web search calls. -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `object: "organization.usage.web_searches.result"` -#### Response + - `"organization.usage.web_searches.result"` -```json -{ - "id": "proj_abc", - "object": "organization.project", - "name": "Project DEF", - "created_at": 1711471533, - "archived_at": 1711471533, - "status": "archived" -} -``` + - `api_key_id: optional string` -## Domain Types + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Project + - `context_level: optional string` -- `Project object { id, created_at, object, 4 more }` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - Represents an individual project. + - `model: optional string` - - `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `project_id: optional string` - - `created_at: number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The Unix timestamp (in seconds) of when the project was created. + - `user_id: optional string` - - `object: "organization.project"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The object type, which is always `organization.project` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `"organization.project"` + The aggregated costs details of the specific time bucket. - - `archived_at: optional number` + - `object: "organization.costs.result"` - The Unix timestamp (in seconds) of when the project was archived or `null`. + - `"organization.costs.result"` - - `external_key_id: optional string` + - `amount: optional object { currency, value }` - The external key associated with the project. + The monetary value in its associated currency. - - `name: optional string` + - `currency: optional string` - The name of the project. This appears in reporting. + Lowercase ISO-4217 currency e.g. "usd" - - `status: optional string` + - `value: optional number` - `active` or `archived` + The numeric value of the cost. -# Users + - `api_key_id: optional string` -## List project users + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. -**get** `/organization/projects/{project_id}/users` + - `line_item: optional string` -Returns a list of users in the project. + When `group_by=line_item`, this field provides the line item of the grouped costs result. -### Path Parameters + - `project_id: optional string` -- `project_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -### Query Parameters + - `quantity: optional number` -- `after: optional string` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `start_time: number` -- `limit: optional number` + - `has_more: boolean` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `next_page: string` -### Returns + - `object: "page"` -- `data: array of ProjectUser` + - `"page"` - - `id: string` +### Usage Audio Transcriptions Response - The identifier, which can be referenced in API endpoints +- `UsageAudioTranscriptionsResponse object { data, has_more, next_page, object }` - - `added_at: number` + - `data: array of object { end_time, object, results, start_time }` - The Unix timestamp (in seconds) of when the project was added. + - `end_time: number` - - `object: "organization.project.user"` + - `object: "bucket"` - The object type, which is always `organization.project.user` + - `"bucket"` - - `"organization.project.user"` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `role: string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - `owner` or `member` + The aggregated completions usage details of the specific time bucket. - - `email: optional string` + - `input_tokens: number` - The email address of the user + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `name: optional string` + - `num_model_requests: number` - The name of the user + The count of requests made to the model. -- `has_more: boolean` + - `object: "organization.usage.completions.result"` -- `object: string` + - `"organization.usage.completions.result"` -- `first_id: optional string` + - `output_tokens: number` -- `last_id: optional string` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `batch: optional boolean` -```json -{ - "data": [ - { - "id": "id", - "added_at": 0, - "object": "organization.project.user", - "role": "role", - "email": "email", - "name": "name" - } - ], - "has_more": true, - "object": "object", - "first_id": "first_id", - "last_id": "last_id" -} -``` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -### Example + - `input_audio_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of uncached audio input tokens used. -#### Response + - `input_cache_write_tokens: optional number` -```json -{ - "object": "list", - "data": [ - { - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 - } - ], - "first_id": "user-abc", - "last_id": "user-xyz", - "has_more": false -} -``` + The aggregated number of input tokens written to the cache. -## Create project user + - `input_cached_audio_tokens: optional number` -**post** `/organization/projects/{project_id}/users` + The aggregated number of cached audio input tokens used. -Adds a user to the project. Users must already be members of the organization to be added to a project. + - `input_cached_image_tokens: optional number` -### Path Parameters + The aggregated number of cached image input tokens used. -- `project_id: string` + - `input_cached_text_tokens: optional number` -### Body Parameters + The aggregated number of cached text input tokens used. -- `role: string` + - `input_cached_tokens: optional number` - `owner` or `member` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `email: optional string` + - `input_image_tokens: optional number` - Email of the user to add. + The aggregated number of uncached image input tokens used. -- `user_id: optional string` + - `input_text_tokens: optional number` - The ID of the user. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. -### Returns + - `input_uncached_tokens: optional number` -- `ProjectUser object { id, added_at, object, 3 more }` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - Represents an individual user in a project. + - `model: optional string` - - `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `output_audio_tokens: optional number` - - `added_at: number` + The aggregated number of audio output tokens used. - The Unix timestamp (in seconds) of when the project was added. + - `output_image_tokens: optional number` - - `object: "organization.project.user"` + The aggregated number of image output tokens used. - The object type, which is always `organization.project.user` + - `output_text_tokens: optional number` - - `"organization.project.user"` + The aggregated number of text output tokens used. - - `role: string` + - `project_id: optional string` - `owner` or `member` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `email: optional string` + - `service_tier: optional string` - The email address of the user + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `name: optional string` + - `user_id: optional string` - The name of the user + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "role": "role" - }' -``` + The aggregated embeddings usage details of the specific time bucket. -#### Response + - `input_tokens: number` -```json -{ - "id": "id", - "added_at": 0, - "object": "organization.project.user", - "role": "role", - "email": "email", - "name": "name" -} -``` + The aggregated number of input tokens used. -### Example + - `num_model_requests: number` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "user_id": "user_abc", - "role": "member" - }' -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.embeddings.result"` -```json -{ - "object": "organization.project.user", - "id": "user_abc", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 -} -``` + - `"organization.usage.embeddings.result"` -## Retrieve project user + - `api_key_id: optional string` -**get** `/organization/projects/{project_id}/users/{user_id}` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Retrieves a user in the project. + - `model: optional string` -### Path Parameters + When `group_by=model`, this field provides the model name of the grouped usage result. -- `project_id: string` + - `project_id: optional string` -- `user_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `ProjectUser object { id, added_at, object, 3 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Represents an individual user in a project. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `id: string` + The aggregated moderations usage details of the specific time bucket. - The identifier, which can be referenced in API endpoints + - `input_tokens: number` - - `added_at: number` + The aggregated number of input tokens used. - The Unix timestamp (in seconds) of when the project was added. + - `num_model_requests: number` - - `object: "organization.project.user"` + The count of requests made to the model. - The object type, which is always `organization.project.user` + - `object: "organization.usage.moderations.result"` - - `"organization.project.user"` + - `"organization.usage.moderations.result"` - - `role: string` + - `api_key_id: optional string` - `owner` or `member` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `email: optional string` + - `model: optional string` - The email address of the user + When `group_by=model`, this field provides the model name of the grouped usage result. - - `name: optional string` + - `project_id: optional string` - The name of the user + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Example + - `user_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -#### Response + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -```json -{ - "id": "id", - "added_at": 0, - "object": "organization.project.user", - "role": "role", - "email": "email", - "name": "name" -} -``` + The aggregated images usage details of the specific time bucket. -### Example + - `images: number` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The number of images processed. -#### Response + - `num_model_requests: number` -```json -{ - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 -} -``` + The count of requests made to the model. -## Modify project user + - `object: "organization.usage.images.result"` -**post** `/organization/projects/{project_id}/users/{user_id}` + - `"organization.usage.images.result"` -Modifies a user's role in the project. + - `api_key_id: optional string` -### Path Parameters + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `project_id: string` + - `model: optional string` -- `user_id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Body Parameters + - `project_id: optional string` -- `role: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - `owner` or `member` + - `size: optional string` -### Returns + When `group_by=size`, this field provides the image size of the grouped usage result. -- `ProjectUser object { id, added_at, object, 3 more }` + - `source: optional string` - Represents an individual user in a project. + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `id: string` + - `user_id: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `added_at: number` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - The Unix timestamp (in seconds) of when the project was added. + The aggregated audio speeches usage details of the specific time bucket. - - `object: "organization.project.user"` + - `characters: number` - The object type, which is always `organization.project.user` + The number of characters processed. - - `"organization.project.user"` + - `num_model_requests: number` - - `role: string` + The count of requests made to the model. - `owner` or `member` + - `object: "organization.usage.audio_speeches.result"` - - `email: optional string` + - `"organization.usage.audio_speeches.result"` - The email address of the user + - `api_key_id: optional string` - - `name: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The name of the user + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "id": "id", - "added_at": 0, - "object": "organization.project.user", - "role": "role", - "email": "email", - "name": "name" -} -``` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role": "owner" - }' -``` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -#### Response + The aggregated audio transcriptions usage details of the specific time bucket. -```json -{ - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 -} -``` + - `num_model_requests: number` -## Delete project user + The count of requests made to the model. -**delete** `/organization/projects/{project_id}/users/{user_id}` + - `object: "organization.usage.audio_transcriptions.result"` -Deletes a user from the project. + - `"organization.usage.audio_transcriptions.result"` -Returns confirmation of project user deletion, or an error if the project is -archived (archived projects have no users). + - `seconds: number` -### Path Parameters + The number of seconds processed. -- `project_id: string` + - `api_key_id: optional string` -- `user_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Returns + - `model: optional string` -- `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. -- `deleted: boolean` + - `project_id: optional string` -- `object: "organization.project.user.deleted"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"organization.project.user.deleted"` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/users/$USER_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -#### Response + The aggregated vector stores usage details of the specific time bucket. -```json -{ - "id": "id", - "deleted": true, - "object": "organization.project.user.deleted" -} -``` + - `object: "organization.usage.vector_stores.result"` -### Example + - `"organization.usage.vector_stores.result"` -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `usage_bytes: number` -#### Response + The vector stores usage in bytes. -```json -{ - "object": "organization.project.user.deleted", - "id": "user_abc", - "deleted": true -} -``` + - `project_id: optional string` -## Domain Types + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Project User + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -- `ProjectUser object { id, added_at, object, 3 more }` + The aggregated code interpreter sessions usage details of the specific time bucket. - Represents an individual user in a project. + - `num_sessions: number` - - `id: string` + The number of code interpreter sessions. - The identifier, which can be referenced in API endpoints + - `object: "organization.usage.code_interpreter_sessions.result"` - - `added_at: number` + - `"organization.usage.code_interpreter_sessions.result"` - The Unix timestamp (in seconds) of when the project was added. + - `project_id: optional string` - - `object: "organization.project.user"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The object type, which is always `organization.project.user` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `"organization.project.user"` + The aggregated file search calls usage details of the specific time bucket. - - `role: string` + - `num_requests: number` - `owner` or `member` + The count of file search calls. - - `email: optional string` + - `object: "organization.usage.file_searches.result"` - The email address of the user + - `"organization.usage.file_searches.result"` - - `name: optional string` + - `api_key_id: optional string` - The name of the user + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### User Delete Response + - `project_id: optional string` -- `UserDeleteResponse object { id, deleted, object }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - - `deleted: boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `object: "organization.project.user.deleted"` + - `vector_store_id: optional string` - - `"organization.project.user.deleted"` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -# Roles + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -## List project user role assignments + The aggregated web search calls usage details of the specific time bucket. -**get** `/projects/{project_id}/users/{user_id}/roles` + - `num_model_requests: number` -Lists the project roles assigned to a user within a project. + The count of model requests. -### Path Parameters + - `num_requests: number` -- `project_id: string` + The count of web search calls. -- `user_id: string` + - `object: "organization.usage.web_searches.result"` -### Query Parameters + - `"organization.usage.web_searches.result"` -- `after: optional string` + - `api_key_id: optional string` - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `limit: optional number` + - `context_level: optional string` - A limit on the number of project role assignments to return. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `order: optional "asc" or "desc"` + - `model: optional string` - Sort order for the returned project roles. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"asc"` + - `project_id: optional string` - - `"desc"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `data: array of object { id, assignment_sources, created_at, 9 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Role assignments returned in the current page. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `id: string` + The aggregated costs details of the specific time bucket. - Identifier for the role. + - `object: "organization.costs.result"` - - `assignment_sources: array of object { principal_id, principal_type }` + - `"organization.costs.result"` - Principals from which the role assignment is inherited, when available. + - `amount: optional object { currency, value }` - - `principal_id: string` + The monetary value in its associated currency. - - `principal_type: string` + - `currency: optional string` - - `created_at: number` + Lowercase ISO-4217 currency e.g. "usd" - When the role was created. + - `value: optional number` - - `created_by: string` + The numeric value of the cost. - Identifier of the actor who created the role. + - `api_key_id: optional string` - - `created_by_user_obj: map[unknown]` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - User details for the actor that created the role, when available. + - `line_item: optional string` - - `description: string` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - Description of the role. + - `project_id: optional string` - - `metadata: map[unknown]` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - Arbitrary metadata stored on the role. + - `quantity: optional number` - - `name: string` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - Name of the role. + - `start_time: number` - - `permissions: array of string` + - `has_more: boolean` - Permissions associated with the role. + - `next_page: string` - - `predefined_role: boolean` + - `object: "page"` - Whether the role is predefined by OpenAI. + - `"page"` - - `resource_type: string` +### Usage Code Interpreter Sessions Response - Resource type the role applies to. +- `UsageCodeInterpreterSessionsResponse object { data, has_more, next_page, object }` - - `updated_at: number` + - `data: array of object { end_time, object, results, start_time }` - When the role was last updated. + - `end_time: number` -- `has_more: boolean` + - `object: "bucket"` - Whether additional assignments are available when paginating. + - `"bucket"` -- `next: string` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - Cursor to fetch the next page of results, or `null` when there are no more assignments. + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -- `object: "list"` + The aggregated completions usage details of the specific time bucket. - Always `list`. + - `input_tokens: number` - - `"list"` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Example + - `num_model_requests: number` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.completions.result"` -```json -{ - "data": [ - { - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + - `"organization.usage.completions.result"` -### Example + - `output_tokens: number` -```http -curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -#### Response + - `api_key_id: optional string` -```json -{ - "object": "list", - "data": [ - { - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false, - "description": "Allows managing API keys for the project", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": { - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com" - }, - "metadata": {} - } - ], - "has_more": false, - "next": null -} -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Assign project role to user + - `batch: optional boolean` -**post** `/projects/{project_id}/users/{user_id}/roles` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -Assigns a project role to a user within a project. + - `input_audio_tokens: optional number` -### Path Parameters + The aggregated number of uncached audio input tokens used. -- `project_id: string` + - `input_cache_write_tokens: optional number` -- `user_id: string` + The aggregated number of input tokens written to the cache. -### Body Parameters + - `input_cached_audio_tokens: optional number` -- `role_id: string` + The aggregated number of cached audio input tokens used. - Identifier of the role to assign. + - `input_cached_image_tokens: optional number` -### Returns + The aggregated number of cached image input tokens used. -- `object: "user.role"` + - `input_cached_text_tokens: optional number` - Always `user.role`. + The aggregated number of cached text input tokens used. - - `"user.role"` + - `input_cached_tokens: optional number` -- `role: Role` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Details about a role that can be assigned through the public Roles API. + - `input_image_tokens: optional number` - - `id: string` + The aggregated number of uncached image input tokens used. - Identifier for the role. + - `input_text_tokens: optional number` - - `description: string` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - Optional description of the role. + - `input_uncached_tokens: optional number` - - `name: string` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - Unique name for the role. + - `model: optional string` - - `object: "role"` + When `group_by=model`, this field provides the model name of the grouped usage result. - Always `role`. + - `output_audio_tokens: optional number` - - `"role"` + The aggregated number of audio output tokens used. - - `permissions: array of string` + - `output_image_tokens: optional number` - Permissions granted by the role. + The aggregated number of image output tokens used. - - `predefined_role: boolean` + - `output_text_tokens: optional number` - Whether the role is predefined and managed by OpenAI. + The aggregated number of text output tokens used. - - `resource_type: string` + - `project_id: optional string` - Resource type the role is bound to (for example `api.organization` or `api.project`). + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `user: OrganizationUser` + - `service_tier: optional string` - Represents an individual `user` within an organization. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `id: string` + - `user_id: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `added_at: number` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - The Unix timestamp (in seconds) of when the user was added. + The aggregated embeddings usage details of the specific time bucket. - - `object: "organization.user"` + - `input_tokens: number` - The object type, which is always `organization.user` + The aggregated number of input tokens used. - - `"organization.user"` + - `num_model_requests: number` - - `api_key_last_used_at: optional number` + The count of requests made to the model. - The Unix timestamp (in seconds) of the user's last API key usage. + - `object: "organization.usage.embeddings.result"` - - `created: optional number` + - `"organization.usage.embeddings.result"` - The Unix timestamp (in seconds) of when the user was created. + - `api_key_id: optional string` - - `developer_persona: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The developer persona metadata for the user. + - `model: optional string` - - `email: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The email address of the user + - `project_id: optional string` - - `is_default: optional boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether this is the organization's default user. + - `user_id: optional string` - - `is_scale_tier_authorized_purchaser: optional boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Whether the user is an authorized purchaser for Scale Tier. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `is_scim_managed: optional boolean` + The aggregated moderations usage details of the specific time bucket. - Whether the user is managed through SCIM. + - `input_tokens: number` - - `is_service_account: optional boolean` + The aggregated number of input tokens used. - Whether the user is a service account. + - `num_model_requests: number` - - `name: optional string` + The count of requests made to the model. - The name of the user + - `object: "organization.usage.moderations.result"` - - `projects: optional object { data, object }` + - `"organization.usage.moderations.result"` - Projects associated with the user, if included. + - `api_key_id: optional string` - - `data: array of object { id, name, role }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `id: optional string` + - `model: optional string` - - `name: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `role: optional string` + - `project_id: optional string` - - `object: "list"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"list"` + - `user_id: optional string` - - `role: optional string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - `owner` or `reader` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `technical_level: optional string` + The aggregated images usage details of the specific time bucket. - The technical level metadata for the user. + - `images: number` - - `user: optional object { id, object, banned, 5 more }` + The number of images processed. - Nested user details. + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - - `object: "user"` + - `object: "organization.usage.images.result"` - - `"user"` + - `"organization.usage.images.result"` - - `banned: optional boolean` + - `api_key_id: optional string` - - `banned_at: optional number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `email: optional string` + - `model: optional string` - - `enabled: optional boolean` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `name: optional string` + - `project_id: optional string` - - `picture: optional string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Example + - `size: optional string` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "role_id": "role_id" - }' -``` + When `group_by=size`, this field provides the image size of the grouped usage result. -#### Response + - `source: optional string` -```json -{ - "object": "user.role", - "role": { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" - }, - "user": { - "id": "id", - "added_at": 0, - "object": "organization.user", - "api_key_last_used_at": 0, - "created": 0, - "developer_persona": "developer_persona", - "email": "email", - "is_default": true, - "is_scale_tier_authorized_purchaser": true, - "is_scim_managed": true, - "is_service_account": true, - "name": "name", - "projects": { - "data": [ - { - "id": "id", - "name": "name", - "role": "role" - } - ], - "object": "list" - }, - "role": "role", - "technical_level": "technical_level", - "user": { - "id": "id", - "object": "user", - "banned": true, - "banned_at": 0, - "email": "email", - "enabled": true, - "name": "name", - "picture": "picture" - } - } -} -``` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -### Example + - `user_id: optional string` -```http -curl -X POST https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_id": "role_01J1F8PROJ" - }' -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -#### Response + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -```json -{ - "object": "user.role", - "user": { - "object": "organization.user", - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com", - "role": "owner", - "added_at": 1711470000 - }, - "role": { - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false - } -} -``` + The aggregated audio speeches usage details of the specific time bucket. -## Retrieve project user role + - `characters: number` -**get** `/projects/{project_id}/users/{user_id}/roles/{role_id}` + The number of characters processed. -Retrieves a project role assigned to a user. + - `num_model_requests: number` -### Path Parameters + The count of requests made to the model. -- `project_id: string` + - `object: "organization.usage.audio_speeches.result"` -- `user_id: string` + - `"organization.usage.audio_speeches.result"` -- `role_id: string` + - `api_key_id: optional string` -### Returns + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `id: string` + - `model: optional string` - Identifier for the role. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `assignment_sources: array of object { principal_id, principal_type }` + - `project_id: optional string` - Principals from which the role assignment is inherited, when available. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `principal_id: string` + - `user_id: optional string` - - `principal_type: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `created_at: number` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - When the role was created. + The aggregated audio transcriptions usage details of the specific time bucket. -- `created_by: string` + - `num_model_requests: number` - Identifier of the actor who created the role. + The count of requests made to the model. -- `created_by_user_obj: map[unknown]` + - `object: "organization.usage.audio_transcriptions.result"` - User details for the actor that created the role, when available. + - `"organization.usage.audio_transcriptions.result"` -- `description: string` + - `seconds: number` - Description of the role. + The number of seconds processed. -- `metadata: map[unknown]` + - `api_key_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `name: string` + - `model: optional string` - Name of the role. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `permissions: array of string` + - `project_id: optional string` - Permissions associated with the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `predefined_role: boolean` + - `user_id: optional string` - Whether the role is predefined by OpenAI. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `resource_type: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - Resource type the role applies to. + The aggregated vector stores usage details of the specific time bucket. -- `updated_at: number` + - `object: "organization.usage.vector_stores.result"` - When the role was last updated. + - `"organization.usage.vector_stores.result"` -### Example + - `usage_bytes: number` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The vector stores usage in bytes. -#### Response + - `project_id: optional string` -```json -{ - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 -} -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Example + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -```http -curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated code interpreter sessions usage details of the specific time bucket. -#### Response + - `num_sessions: number` -```json -{ - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false, - "description": "Allows managing API keys for the project", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": null, - "metadata": {}, - "assignment_sources": null -} -``` + The number of code interpreter sessions. -## Unassign project role from user + - `object: "organization.usage.code_interpreter_sessions.result"` -**delete** `/projects/{project_id}/users/{user_id}/roles/{role_id}` + - `"organization.usage.code_interpreter_sessions.result"` -Unassigns a project role from a user within a project. + - `project_id: optional string` -### Path Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `project_id: string` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -- `user_id: string` + The aggregated file search calls usage details of the specific time bucket. -- `role_id: string` + - `num_requests: number` -### Returns + The count of file search calls. -- `deleted: boolean` + - `object: "organization.usage.file_searches.result"` - Whether the assignment was removed. + - `"organization.usage.file_searches.result"` -- `object: string` + - `api_key_id: optional string` - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/users/$USER_ID/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "deleted": true, - "object": "object" -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `vector_store_id: optional string` -```http -curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -#### Response + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -```json -{ - "object": "user.role.deleted", - "deleted": true -} -``` + The aggregated web search calls usage details of the specific time bucket. + + - `num_model_requests: number` + + The count of model requests. + + - `num_requests: number` + + The count of web search calls. + + - `object: "organization.usage.web_searches.result"` + + - `"organization.usage.web_searches.result"` + + - `api_key_id: optional string` + + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. + + - `context_level: optional string` + + When `group_by=context_level`, this field provides the search context size of the grouped usage result. + + - `model: optional string` + + When `group_by=model`, this field provides the model name of the grouped usage result. -## Domain Types + - `project_id: optional string` -### Role List Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` + - `user_id: optional string` - Detailed information about a role assignment entry returned when listing assignments. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - Identifier for the role. + The aggregated costs details of the specific time bucket. - - `assignment_sources: array of object { principal_id, principal_type }` + - `object: "organization.costs.result"` - Principals from which the role assignment is inherited, when available. + - `"organization.costs.result"` - - `principal_id: string` + - `amount: optional object { currency, value }` - - `principal_type: string` + The monetary value in its associated currency. - - `created_at: number` + - `currency: optional string` - When the role was created. + Lowercase ISO-4217 currency e.g. "usd" - - `created_by: string` + - `value: optional number` - Identifier of the actor who created the role. + The numeric value of the cost. - - `created_by_user_obj: map[unknown]` + - `api_key_id: optional string` - User details for the actor that created the role, when available. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `description: string` + - `line_item: optional string` - Description of the role. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `metadata: map[unknown]` + - `project_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `name: string` + - `quantity: optional number` - Name of the role. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `permissions: array of string` + - `start_time: number` - Permissions associated with the role. + - `has_more: boolean` - - `predefined_role: boolean` + - `next_page: string` - Whether the role is predefined by OpenAI. + - `object: "page"` - - `resource_type: string` + - `"page"` - Resource type the role applies to. +### Usage Completions Response - - `updated_at: number` +- `UsageCompletionsResponse object { data, has_more, next_page, object }` - When the role was last updated. + - `data: array of object { end_time, object, results, start_time }` -### Role Create Response + - `end_time: number` -- `RoleCreateResponse object { object, role, user }` + - `object: "bucket"` - Role assignment linking a user to a role. + - `"bucket"` - - `object: "user.role"` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - Always `user.role`. + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - - `"user.role"` + The aggregated completions usage details of the specific time bucket. - - `role: Role` + - `input_tokens: number` - Details about a role that can be assigned through the public Roles API. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `id: string` + - `num_model_requests: number` - Identifier for the role. + The count of requests made to the model. - - `description: string` + - `object: "organization.usage.completions.result"` - Optional description of the role. + - `"organization.usage.completions.result"` - - `name: string` + - `output_tokens: number` - Unique name for the role. + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `object: "role"` + - `api_key_id: optional string` - Always `role`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"role"` + - `batch: optional boolean` - - `permissions: array of string` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - Permissions granted by the role. + - `input_audio_tokens: optional number` - - `predefined_role: boolean` + The aggregated number of uncached audio input tokens used. - Whether the role is predefined and managed by OpenAI. + - `input_cache_write_tokens: optional number` - - `resource_type: string` + The aggregated number of input tokens written to the cache. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `input_cached_audio_tokens: optional number` - - `user: OrganizationUser` + The aggregated number of cached audio input tokens used. - Represents an individual `user` within an organization. + - `input_cached_image_tokens: optional number` - - `id: string` + The aggregated number of cached image input tokens used. - The identifier, which can be referenced in API endpoints + - `input_cached_text_tokens: optional number` - - `added_at: number` + The aggregated number of cached text input tokens used. - The Unix timestamp (in seconds) of when the user was added. + - `input_cached_tokens: optional number` - - `object: "organization.user"` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The object type, which is always `organization.user` + - `input_image_tokens: optional number` - - `"organization.user"` + The aggregated number of uncached image input tokens used. - - `api_key_last_used_at: optional number` + - `input_text_tokens: optional number` - The Unix timestamp (in seconds) of the user's last API key usage. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `created: optional number` + - `input_uncached_tokens: optional number` - The Unix timestamp (in seconds) of when the user was created. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `developer_persona: optional string` + - `model: optional string` - The developer persona metadata for the user. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `email: optional string` + - `output_audio_tokens: optional number` - The email address of the user + The aggregated number of audio output tokens used. - - `is_default: optional boolean` + - `output_image_tokens: optional number` - Whether this is the organization's default user. + The aggregated number of image output tokens used. - - `is_scale_tier_authorized_purchaser: optional boolean` + - `output_text_tokens: optional number` - Whether the user is an authorized purchaser for Scale Tier. + The aggregated number of text output tokens used. - - `is_scim_managed: optional boolean` + - `project_id: optional string` - Whether the user is managed through SCIM. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `is_service_account: optional boolean` + - `service_tier: optional string` - Whether the user is a service account. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `name: optional string` + - `user_id: optional string` - The name of the user + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `projects: optional object { data, object }` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Projects associated with the user, if included. + The aggregated embeddings usage details of the specific time bucket. - - `data: array of object { id, name, role }` + - `input_tokens: number` - - `id: optional string` + The aggregated number of input tokens used. - - `name: optional string` + - `num_model_requests: number` - - `role: optional string` + The count of requests made to the model. - - `object: "list"` + - `object: "organization.usage.embeddings.result"` - - `"list"` + - `"organization.usage.embeddings.result"` - - `role: optional string` + - `api_key_id: optional string` - `owner` or `reader` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `technical_level: optional string` + - `model: optional string` - The technical level metadata for the user. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `user: optional object { id, object, banned, 5 more }` + - `project_id: optional string` - Nested user details. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - - `object: "user"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"user"` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `banned: optional boolean` + The aggregated moderations usage details of the specific time bucket. - - `banned_at: optional number` + - `input_tokens: number` - - `email: optional string` + The aggregated number of input tokens used. - - `enabled: optional boolean` + - `num_model_requests: number` - - `name: optional string` + The count of requests made to the model. - - `picture: optional string` + - `object: "organization.usage.moderations.result"` -### Role Retrieve Response + - `"organization.usage.moderations.result"` -- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` + - `api_key_id: optional string` - Detailed information about a role assignment entry returned when listing assignments. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `id: string` + - `model: optional string` - Identifier for the role. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `assignment_sources: array of object { principal_id, principal_type }` + - `project_id: optional string` - Principals from which the role assignment is inherited, when available. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `principal_id: string` + - `user_id: optional string` - - `principal_type: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `created_at: number` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - When the role was created. + The aggregated images usage details of the specific time bucket. - - `created_by: string` + - `images: number` - Identifier of the actor who created the role. + The number of images processed. - - `created_by_user_obj: map[unknown]` + - `num_model_requests: number` - User details for the actor that created the role, when available. + The count of requests made to the model. - - `description: string` + - `object: "organization.usage.images.result"` - Description of the role. + - `"organization.usage.images.result"` - - `metadata: map[unknown]` + - `api_key_id: optional string` - Arbitrary metadata stored on the role. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `name: string` + - `model: optional string` - Name of the role. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `permissions: array of string` + - `project_id: optional string` - Permissions associated with the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `predefined_role: boolean` + - `size: optional string` - Whether the role is predefined by OpenAI. + When `group_by=size`, this field provides the image size of the grouped usage result. - - `resource_type: string` + - `source: optional string` - Resource type the role applies to. + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `updated_at: number` + - `user_id: optional string` - When the role was last updated. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Role Delete Response + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -- `RoleDeleteResponse object { deleted, object }` + The aggregated audio speeches usage details of the specific time bucket. - Confirmation payload returned after unassigning a role. + - `characters: number` - - `deleted: boolean` + The number of characters processed. - Whether the assignment was removed. + - `num_model_requests: number` - - `object: string` + The count of requests made to the model. - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + - `object: "organization.usage.audio_speeches.result"` -# Service Accounts + - `"organization.usage.audio_speeches.result"` -## List project service accounts + - `api_key_id: optional string` -**get** `/organization/projects/{project_id}/service_accounts` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Returns a list of service accounts in the project. + - `model: optional string` -### Path Parameters + When `group_by=model`, this field provides the model name of the grouped usage result. -- `project_id: string` + - `project_id: optional string` -### Query Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `after: optional string` + - `user_id: optional string` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `limit: optional number` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The aggregated audio transcriptions usage details of the specific time bucket. -### Returns + - `num_model_requests: number` -- `data: array of ProjectServiceAccount` + The count of requests made to the model. - - `id: string` + - `object: "organization.usage.audio_transcriptions.result"` - The identifier, which can be referenced in API endpoints + - `"organization.usage.audio_transcriptions.result"` - - `created_at: number` + - `seconds: number` - The Unix timestamp (in seconds) of when the service account was created + The number of seconds processed. - - `name: string` + - `api_key_id: optional string` - The name of the service account + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `object: "organization.project.service_account"` + - `model: optional string` - The object type, which is always `organization.project.service_account` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"organization.project.service_account"` + - `project_id: optional string` - - `role: "owner" or "member" or "none"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - `owner`, `member`, or `none` + - `user_id: optional string` - - `"owner"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"member"` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - - `"none"` + The aggregated vector stores usage details of the specific time bucket. -- `has_more: boolean` + - `object: "organization.usage.vector_stores.result"` -- `object: "list"` + - `"organization.usage.vector_stores.result"` - - `"list"` + - `usage_bytes: number` -- `first_id: optional string` + The vector stores usage in bytes. -- `last_id: optional string` + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -#### Response + The aggregated code interpreter sessions usage details of the specific time bucket. -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "name": "name", - "object": "organization.project.service_account", - "role": "owner" - } - ], - "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" -} -``` + - `num_sessions: number` -### Example + The number of code interpreter sessions. -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `object: "organization.usage.code_interpreter_sessions.result"` -#### Response + - `"organization.usage.code_interpreter_sessions.result"` -```json -{ - "object": "list", - "data": [ - { - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Service Account", - "role": "owner", - "created_at": 1711471533 - } - ], - "first_id": "svc_acct_abc", - "last_id": "svc_acct_xyz", - "has_more": false -} -``` + - `project_id: optional string` -## Create project service account + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -**post** `/organization/projects/{project_id}/service_accounts` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -Creates a new service account in the project. By default, this also returns an unredacted API key for the service account. + The aggregated file search calls usage details of the specific time bucket. -### Path Parameters + - `num_requests: number` -- `project_id: string` + The count of file search calls. -### Body Parameters + - `object: "organization.usage.file_searches.result"` -- `name: string` + - `"organization.usage.file_searches.result"` - The name of the service account being created. + - `api_key_id: optional string` -- `create_service_account_only: optional boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Create the service account without default roles or an API key. + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `id: string` + - `user_id: optional string` -- `api_key: object { id, created_at, name, 2 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `vector_store_id: optional string` - - `created_at: number` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - - `name: string` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `object: "organization.project.service_account.api_key"` + The aggregated web search calls usage details of the specific time bucket. - The object type, which is always `organization.project.service_account.api_key` + - `num_model_requests: number` - - `"organization.project.service_account.api_key"` + The count of model requests. - - `value: string` + - `num_requests: number` -- `created_at: number` + The count of web search calls. -- `name: string` + - `object: "organization.usage.web_searches.result"` -- `object: "organization.project.service_account"` + - `"organization.usage.web_searches.result"` - - `"organization.project.service_account"` + - `api_key_id: optional string` -- `role: "member" or "none"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Service accounts created with default project membership have role `member`. Accounts created with `create_service_account_only` have role `none`. + - `context_level: optional string` - - `"member"` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `"none"` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "name": "name" - }' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "id": "id", - "api_key": { - "id": "id", - "created_at": 0, - "name": "name", - "object": "organization.project.service_account.api_key", - "value": "value" - }, - "created_at": 0, - "name": "name", - "object": "organization.project.service_account", - "role": "member" -} -``` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Production App" - }' -``` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` -#### Response + The aggregated costs details of the specific time bucket. -```json -{ - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Production App", - "role": "member", - "created_at": 1711471533, - "api_key": { - "object": "organization.project.service_account.api_key", - "value": "sk-abcdefghijklmnop123", - "name": "Secret Key", - "created_at": 1711471533, - "id": "key_abc" - } -} -``` + - `object: "organization.costs.result"` -## Retrieve project service account + - `"organization.costs.result"` -**get** `/organization/projects/{project_id}/service_accounts/{service_account_id}` + - `amount: optional object { currency, value }` -Retrieves a service account in the project. + The monetary value in its associated currency. -### Path Parameters + - `currency: optional string` -- `project_id: string` + Lowercase ISO-4217 currency e.g. "usd" -- `service_account_id: string` + - `value: optional number` -### Returns + The numeric value of the cost. -- `ProjectServiceAccount object { id, created_at, name, 2 more }` + - `api_key_id: optional string` - Represents an individual service account in a project. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `id: string` + - `line_item: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `created_at: number` + - `project_id: optional string` - The Unix timestamp (in seconds) of when the service account was created + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `name: string` + - `quantity: optional number` - The name of the service account + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `object: "organization.project.service_account"` + - `start_time: number` - The object type, which is always `organization.project.service_account` + - `has_more: boolean` - - `"organization.project.service_account"` + - `next_page: string` - - `role: "owner" or "member" or "none"` + - `object: "page"` - `owner`, `member`, or `none` + - `"page"` - - `"owner"` +### Usage Costs Response - - `"member"` +- `UsageCostsResponse object { data, has_more, next_page, object }` - - `"none"` + - `data: array of object { end_time, object, results, start_time }` -### Example + - `end_time: number` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `object: "bucket"` -#### Response + - `"bucket"` -```json -{ - "id": "id", - "created_at": 0, - "name": "name", - "object": "organization.project.service_account", - "role": "owner" -} -``` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -### Example + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated completions usage details of the specific time bucket. -#### Response + - `input_tokens: number` -```json -{ - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Service Account", - "role": "owner", - "created_at": 1711471533 -} -``` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -## Update project service account + - `num_model_requests: number` -**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}` + The count of requests made to the model. -Updates a service account in the project. + - `object: "organization.usage.completions.result"` -### Path Parameters + - `"organization.usage.completions.result"` -- `project_id: string` + - `output_tokens: number` -- `service_account_id: string` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Body Parameters + - `api_key_id: optional string` -- `name: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The updated service account name. + - `batch: optional boolean` -- `role: optional "member" or "owner"` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - The updated service account role. + - `input_audio_tokens: optional number` - - `"member"` + The aggregated number of uncached audio input tokens used. - - `"owner"` + - `input_cache_write_tokens: optional number` -### Returns + The aggregated number of input tokens written to the cache. -- `ProjectServiceAccount object { id, created_at, name, 2 more }` + - `input_cached_audio_tokens: optional number` - Represents an individual service account in a project. + The aggregated number of cached audio input tokens used. - - `id: string` + - `input_cached_image_tokens: optional number` - The identifier, which can be referenced in API endpoints + The aggregated number of cached image input tokens used. - - `created_at: number` + - `input_cached_text_tokens: optional number` - The Unix timestamp (in seconds) of when the service account was created + The aggregated number of cached text input tokens used. - - `name: string` + - `input_cached_tokens: optional number` - The name of the service account + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `object: "organization.project.service_account"` + - `input_image_tokens: optional number` - The object type, which is always `organization.project.service_account` + The aggregated number of uncached image input tokens used. - - `"organization.project.service_account"` + - `input_text_tokens: optional number` - - `role: "owner" or "member" or "none"` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - `owner`, `member`, or `none` + - `input_uncached_tokens: optional number` - - `"owner"` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `"member"` + - `model: optional string` - - `"none"` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Example + - `output_audio_tokens: optional number` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + The aggregated number of audio output tokens used. -#### Response + - `output_image_tokens: optional number` -```json -{ - "id": "id", - "created_at": 0, - "name": "name", - "object": "organization.project.service_account", - "role": "owner" -} -``` + The aggregated number of image output tokens used. -### Example + - `output_text_tokens: optional number` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Updated service account", - "role": "member" - }' -``` + The aggregated number of text output tokens used. -#### Response + - `project_id: optional string` -```json -{ - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Updated service account", - "role": "member", - "created_at": 1711471533 -} -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -## Delete project service account + - `service_tier: optional string` -**delete** `/organization/projects/{project_id}/service_accounts/{service_account_id}` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -Deletes a service account from the project. + - `user_id: optional string` -Returns confirmation of service account deletion, or an error if the project -is archived (archived projects have no service accounts). + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Path Parameters + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -- `project_id: string` + The aggregated embeddings usage details of the specific time bucket. -- `service_account_id: string` + - `input_tokens: number` -### Returns + The aggregated number of input tokens used. -- `id: string` + - `num_model_requests: number` -- `deleted: boolean` + The count of requests made to the model. -- `object: "organization.project.service_account.deleted"` + - `object: "organization.usage.embeddings.result"` - - `"organization.project.service_account.deleted"` + - `"organization.usage.embeddings.result"` -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "id": "id", - "deleted": true, - "object": "organization.project.service_account.deleted" -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "object": "organization.project.service_account.deleted", - "id": "svc_acct_abc", - "deleted": true -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. + + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` + + The aggregated moderations usage details of the specific time bucket. -## Domain Types + - `input_tokens: number` -### Project Service Account + The aggregated number of input tokens used. -- `ProjectServiceAccount object { id, created_at, name, 2 more }` + - `num_model_requests: number` - Represents an individual service account in a project. + The count of requests made to the model. - - `id: string` + - `object: "organization.usage.moderations.result"` - The identifier, which can be referenced in API endpoints + - `"organization.usage.moderations.result"` - - `created_at: number` + - `api_key_id: optional string` - The Unix timestamp (in seconds) of when the service account was created + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `name: string` + - `model: optional string` - The name of the service account + When `group_by=model`, this field provides the model name of the grouped usage result. - - `object: "organization.project.service_account"` + - `project_id: optional string` - The object type, which is always `organization.project.service_account` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"organization.project.service_account"` + - `user_id: optional string` - - `role: "owner" or "member" or "none"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - `owner`, `member`, or `none` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `"owner"` + The aggregated images usage details of the specific time bucket. - - `"member"` + - `images: number` - - `"none"` + The number of images processed. -### Service Account Create Response + - `num_model_requests: number` -- `ServiceAccountCreateResponse object { id, api_key, created_at, 3 more }` + The count of requests made to the model. - - `id: string` + - `object: "organization.usage.images.result"` - - `api_key: object { id, created_at, name, 2 more }` + - `"organization.usage.images.result"` - - `id: string` + - `api_key_id: optional string` - - `created_at: number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `name: string` + - `model: optional string` - - `object: "organization.project.service_account.api_key"` + When `group_by=model`, this field provides the model name of the grouped usage result. - The object type, which is always `organization.project.service_account.api_key` + - `project_id: optional string` - - `"organization.project.service_account.api_key"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `value: string` + - `size: optional string` - - `created_at: number` + When `group_by=size`, this field provides the image size of the grouped usage result. - - `name: string` + - `source: optional string` - - `object: "organization.project.service_account"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `"organization.project.service_account"` + - `user_id: optional string` - - `role: "member" or "none"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Service accounts created with default project membership have role `member`. Accounts created with `create_service_account_only` have role `none`. + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `"member"` + The aggregated audio speeches usage details of the specific time bucket. - - `"none"` + - `characters: number` -### Service Account Delete Response + The number of characters processed. -- `ServiceAccountDeleteResponse object { id, deleted, object }` + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - - `deleted: boolean` + - `object: "organization.usage.audio_speeches.result"` - - `object: "organization.project.service_account.deleted"` + - `"organization.usage.audio_speeches.result"` - - `"organization.project.service_account.deleted"` + - `api_key_id: optional string` -# API Keys + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Create project service account API key + - `model: optional string` -**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys` + When `group_by=model`, this field provides the model name of the grouped usage result. -Creates an API key for a service account in the project. + - `project_id: optional string` -### Path Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `project_id: string` + - `user_id: optional string` - The ID of the project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `service_account_id: string` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - The ID of the service account. + The aggregated audio transcriptions usage details of the specific time bucket. -### Body Parameters + - `num_model_requests: number` -- `name: optional string` + The count of requests made to the model. - API key name. + - `object: "organization.usage.audio_transcriptions.result"` -- `scopes: optional array of string` + - `"organization.usage.audio_transcriptions.result"` - API key scopes. + - `seconds: number` -### Returns + The number of seconds processed. -- `id: string` + - `api_key_id: optional string` - The identifier of the API key. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `created_at: number` + - `model: optional string` - The Unix timestamp (in seconds) when the API key was created. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `name: string` + - `project_id: optional string` - The name of the API key. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `object: "organization.project.service_account.api_key"` + - `user_id: optional string` - The object type, which is always `organization.project.service_account.api_key` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"organization.project.service_account.api_key"` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -- `value: string` + The aggregated vector stores usage details of the specific time bucket. - The unredacted API key value. + - `object: "organization.usage.vector_stores.result"` -### Example + - `"organization.usage.vector_stores.result"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/service_accounts/$SERVICE_ACCOUNT_ID/api_keys \ - -X POST \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `usage_bytes: number` -#### Response + The vector stores usage in bytes. -```json -{ - "id": "id", - "created_at": 0, - "name": "name", - "object": "organization.project.service_account.api_key", - "value": "value" -} -``` + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc/api_keys \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Production App", - "scopes": ["api.responses.write"] - }' -``` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` -#### Response + The aggregated code interpreter sessions usage details of the specific time bucket. -```json -{ - "object": "organization.project.service_account.api_key", - "value": "sk-abcdefghijklmnop123", - "name": "Production App", - "created_at": 1711471533, - "id": "key_abc" -} -``` + - `num_sessions: number` -## Domain Types + The number of code interpreter sessions. -### API Key Create Response + - `object: "organization.usage.code_interpreter_sessions.result"` -- `APIKeyCreateResponse object { id, created_at, name, 2 more }` + - `"organization.usage.code_interpreter_sessions.result"` - - `id: string` + - `project_id: optional string` - The identifier of the API key. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `created_at: number` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The Unix timestamp (in seconds) when the API key was created. + The aggregated file search calls usage details of the specific time bucket. - - `name: string` + - `num_requests: number` - The name of the API key. + The count of file search calls. - - `object: "organization.project.service_account.api_key"` + - `object: "organization.usage.file_searches.result"` - The object type, which is always `organization.project.service_account.api_key` + - `"organization.usage.file_searches.result"` - - `"organization.project.service_account.api_key"` + - `api_key_id: optional string` - - `value: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The unredacted API key value. + - `project_id: optional string` -# API Keys + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -## List project API keys + - `user_id: optional string` -**get** `/organization/projects/{project_id}/api_keys` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -Returns a list of API keys in the project. + - `vector_store_id: optional string` -### Path Parameters + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -- `project_id: string` + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -### Query Parameters + The aggregated web search calls usage details of the specific time bucket. -- `after: optional string` + - `num_model_requests: number` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + The count of model requests. -- `limit: optional number` + - `num_requests: number` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The count of web search calls. -- `owner_project_access: optional "active" or "inactive" or "any"` + - `object: "organization.usage.web_searches.result"` - Filter API keys by whether the owner currently has effective access to the project. Use `active` for owners with access, `inactive` for owners without access, or `any` for all enabled project API keys. If omitted, the endpoint applies its existing membership-based visibility rules, which may exclude some enabled keys. + - `"organization.usage.web_searches.result"` - - `"active"` + - `api_key_id: optional string` - - `"inactive"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"any"` + - `context_level: optional string` -### Returns + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `data: array of ProjectAPIKey` + - `model: optional string` - - `id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - The identifier, which can be referenced in API endpoints + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. + + - `user_id: optional string` + + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `created_at: number` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - The Unix timestamp (in seconds) of when the API key was created + The aggregated costs details of the specific time bucket. - - `last_used_at: number` + - `object: "organization.costs.result"` - The Unix timestamp (in seconds) of when the API key was last used. + - `"organization.costs.result"` - - `name: string` + - `amount: optional object { currency, value }` - The name of the API key + The monetary value in its associated currency. - - `object: "organization.project.api_key"` + - `currency: optional string` - The object type, which is always `organization.project.api_key` + Lowercase ISO-4217 currency e.g. "usd" - - `"organization.project.api_key"` + - `value: optional number` - - `owner: object { service_account, type, user }` + The numeric value of the cost. - - `service_account: optional object { id, created_at, name, role }` + - `api_key_id: optional string` - The service account that owns a project API key. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `id: string` + - `line_item: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `created_at: number` + - `project_id: optional string` - The Unix timestamp (in seconds) of when the service account was created. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `name: string` + - `quantity: optional number` - The name of the service account. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `role: string` + - `start_time: number` - The service account's project role. + - `has_more: boolean` - - `type: optional "user" or "service_account"` + - `next_page: string` - `user` or `service_account` + - `object: "page"` - - `"user"` + - `"page"` - - `"service_account"` +### Usage Embeddings Response - - `user: optional object { id, created_at, email, 2 more }` +- `UsageEmbeddingsResponse object { data, has_more, next_page, object }` - The user that owns a project API key. + - `data: array of object { end_time, object, results, start_time }` - - `id: string` + - `end_time: number` - The identifier, which can be referenced in API endpoints + - `object: "bucket"` - - `created_at: number` + - `"bucket"` - The Unix timestamp (in seconds) of when the user was created. + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` - - `email: string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` - The email address of the user. + The aggregated completions usage details of the specific time bucket. - - `name: string` + - `input_tokens: number` - The name of the user. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `role: string` + - `num_model_requests: number` - The user's project role. + The count of requests made to the model. - - `owner_project_access: "active" or "inactive"` + - `object: "organization.usage.completions.result"` - Whether the API key's owner currently has effective access to the project. + - `"organization.usage.completions.result"` - - `"active"` + - `output_tokens: number` - - `"inactive"` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `redacted_value: string` + - `api_key_id: optional string` - The redacted value of the API key + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `has_more: boolean` + - `batch: optional boolean` -- `object: "list"` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - - `"list"` + - `input_audio_tokens: optional number` -- `first_id: optional string` + The aggregated number of uncached audio input tokens used. -- `last_id: optional string` + - `input_cache_write_tokens: optional number` -### Example + The aggregated number of input tokens written to the cache. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `input_cached_audio_tokens: optional number` -#### Response + The aggregated number of cached audio input tokens used. -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "last_used_at": 0, - "name": "name", - "object": "organization.project.api_key", - "owner": { - "service_account": { - "id": "id", - "created_at": 0, - "name": "name", - "role": "role" - }, - "type": "user", - "user": { - "id": "id", - "created_at": 0, - "email": "email", - "name": "name", - "role": "role" - } - }, - "owner_project_access": "active", - "redacted_value": "redacted_value" - } - ], - "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" -} -``` + - `input_cached_image_tokens: optional number` -### Example + The aggregated number of cached image input tokens used. -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20&owner_project_access=any \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `input_cached_text_tokens: optional number` -#### Response + The aggregated number of cached text input tokens used. -```json -{ - "object": "list", - "data": [ - { - "object": "organization.project.api_key", - "redacted_value": "sk-abc...def", - "name": "My API Key", - "created_at": 1711471533, - "last_used_at": 1711471534, - "id": "key_abc", - "owner_project_access": "active", - "owner": { - "type": "user", - "user": { - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "created_at": 1711471533 - } - } - } - ], - "first_id": "key_abc", - "last_id": "key_xyz", - "has_more": false -} -``` + - `input_cached_tokens: optional number` -## Retrieve project API key + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -**get** `/organization/projects/{project_id}/api_keys/{api_key_id}` + - `input_image_tokens: optional number` -Retrieves an API key in the project. + The aggregated number of uncached image input tokens used. -### Path Parameters + - `input_text_tokens: optional number` -- `project_id: string` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. -- `api_key_id: string` + - `input_uncached_tokens: optional number` -### Returns + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. -- `ProjectAPIKey object { id, created_at, last_used_at, 5 more }` + - `model: optional string` - Represents an individual API key in a project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `id: string` + - `output_audio_tokens: optional number` - The identifier, which can be referenced in API endpoints + The aggregated number of audio output tokens used. - - `created_at: number` + - `output_image_tokens: optional number` - The Unix timestamp (in seconds) of when the API key was created + The aggregated number of image output tokens used. - - `last_used_at: number` + - `output_text_tokens: optional number` - The Unix timestamp (in seconds) of when the API key was last used. + The aggregated number of text output tokens used. - - `name: string` + - `project_id: optional string` - The name of the API key + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `object: "organization.project.api_key"` + - `service_tier: optional string` - The object type, which is always `organization.project.api_key` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `"organization.project.api_key"` + - `user_id: optional string` - - `owner: object { service_account, type, user }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `service_account: optional object { id, created_at, name, role }` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - The service account that owns a project API key. + The aggregated embeddings usage details of the specific time bucket. - - `id: string` + - `input_tokens: number` - The identifier, which can be referenced in API endpoints + The aggregated number of input tokens used. - - `created_at: number` + - `num_model_requests: number` - The Unix timestamp (in seconds) of when the service account was created. + The count of requests made to the model. - - `name: string` + - `object: "organization.usage.embeddings.result"` - The name of the service account. + - `"organization.usage.embeddings.result"` - - `role: string` + - `api_key_id: optional string` - The service account's project role. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `type: optional "user" or "service_account"` + - `model: optional string` - `user` or `service_account` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"user"` + - `project_id: optional string` - - `"service_account"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `user: optional object { id, created_at, email, 2 more }` + - `user_id: optional string` - The user that owns a project API key. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - The identifier, which can be referenced in API endpoints + The aggregated moderations usage details of the specific time bucket. - - `created_at: number` + - `input_tokens: number` - The Unix timestamp (in seconds) of when the user was created. + The aggregated number of input tokens used. - - `email: string` + - `num_model_requests: number` - The email address of the user. + The count of requests made to the model. - - `name: string` + - `object: "organization.usage.moderations.result"` - The name of the user. + - `"organization.usage.moderations.result"` - - `role: string` + - `api_key_id: optional string` - The user's project role. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `owner_project_access: "active" or "inactive"` + - `model: optional string` - Whether the API key's owner currently has effective access to the project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"active"` + - `project_id: optional string` - - `"inactive"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `redacted_value: string` + - `user_id: optional string` - The redacted value of the API key + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys/$API_KEY_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated images usage details of the specific time bucket. -#### Response + - `images: number` -```json -{ - "id": "id", - "created_at": 0, - "last_used_at": 0, - "name": "name", - "object": "organization.project.api_key", - "owner": { - "service_account": { - "id": "id", - "created_at": 0, - "name": "name", - "role": "role" - }, - "type": "user", - "user": { - "id": "id", - "created_at": 0, - "email": "email", - "name": "name", - "role": "role" - } - }, - "owner_project_access": "active", - "redacted_value": "redacted_value" -} -``` + The number of images processed. -### Example + - `num_model_requests: number` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.images.result"` -```json -{ - "object": "organization.project.api_key", - "redacted_value": "sk-abc...def", - "name": "My API Key", - "created_at": 1711471533, - "last_used_at": 1711471534, - "id": "key_abc", - "owner_project_access": "active", - "owner": { - "type": "user", - "user": { - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "created_at": 1711471533 - } - } -} -``` + - `"organization.usage.images.result"` -## Delete project API key + - `api_key_id: optional string` -**delete** `/organization/projects/{project_id}/api_keys/{api_key_id}` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -Deletes an API key from the project. + - `model: optional string` -Returns confirmation of the key deletion, or an error if the key belonged to -a service account. + When `group_by=model`, this field provides the model name of the grouped usage result. -### Path Parameters + - `project_id: optional string` -- `project_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `api_key_id: string` + - `size: optional string` -### Returns + When `group_by=size`, this field provides the image size of the grouped usage result. -- `id: string` + - `source: optional string` -- `deleted: boolean` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -- `object: "organization.project.api_key.deleted"` + - `user_id: optional string` - - `"organization.project.api_key.deleted"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/api_keys/$API_KEY_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated audio speeches usage details of the specific time bucket. -#### Response + - `characters: number` -```json -{ - "id": "id", - "deleted": true, - "object": "organization.project.api_key.deleted" -} -``` + The number of characters processed. -### Example + - `num_model_requests: number` -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.audio_speeches.result"` -```json -{ - "object": "organization.project.api_key.deleted", - "id": "key_abc", - "deleted": true -} -``` + - `"organization.usage.audio_speeches.result"` -## Domain Types + - `api_key_id: optional string` -### Project API Key + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `ProjectAPIKey object { id, created_at, last_used_at, 5 more }` + - `model: optional string` - Represents an individual API key in a project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `id: string` + - `project_id: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `created_at: number` + - `user_id: optional string` - The Unix timestamp (in seconds) of when the API key was created + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `last_used_at: number` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - The Unix timestamp (in seconds) of when the API key was last used. + The aggregated audio transcriptions usage details of the specific time bucket. - - `name: string` + - `num_model_requests: number` - The name of the API key + The count of requests made to the model. - - `object: "organization.project.api_key"` + - `object: "organization.usage.audio_transcriptions.result"` - The object type, which is always `organization.project.api_key` + - `"organization.usage.audio_transcriptions.result"` - - `"organization.project.api_key"` + - `seconds: number` - - `owner: object { service_account, type, user }` + The number of seconds processed. - - `service_account: optional object { id, created_at, name, role }` + - `api_key_id: optional string` - The service account that owns a project API key. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `id: string` + - `model: optional string` - The identifier, which can be referenced in API endpoints + When `group_by=model`, this field provides the model name of the grouped usage result. - - `created_at: number` + - `project_id: optional string` - The Unix timestamp (in seconds) of when the service account was created. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: string` + - `user_id: optional string` - The name of the service account. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `role: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - The service account's project role. + The aggregated vector stores usage details of the specific time bucket. - - `type: optional "user" or "service_account"` + - `object: "organization.usage.vector_stores.result"` - `user` or `service_account` + - `"organization.usage.vector_stores.result"` - - `"user"` + - `usage_bytes: number` - - `"service_account"` + The vector stores usage in bytes. - - `user: optional object { id, created_at, email, 2 more }` + - `project_id: optional string` - The user that owns a project API key. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - The identifier, which can be referenced in API endpoints + The aggregated code interpreter sessions usage details of the specific time bucket. - - `created_at: number` + - `num_sessions: number` - The Unix timestamp (in seconds) of when the user was created. + The number of code interpreter sessions. - - `email: string` + - `object: "organization.usage.code_interpreter_sessions.result"` - The email address of the user. + - `"organization.usage.code_interpreter_sessions.result"` - - `name: string` + - `project_id: optional string` - The name of the user. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `role: string` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The user's project role. + The aggregated file search calls usage details of the specific time bucket. - - `owner_project_access: "active" or "inactive"` + - `num_requests: number` - Whether the API key's owner currently has effective access to the project. + The count of file search calls. - - `"active"` + - `object: "organization.usage.file_searches.result"` - - `"inactive"` + - `"organization.usage.file_searches.result"` - - `redacted_value: string` + - `api_key_id: optional string` - The redacted value of the API key + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### API Key Delete Response + - `project_id: optional string` -- `APIKeyDeleteResponse object { id, deleted, object }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `user_id: optional string` - - `deleted: boolean` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `object: "organization.project.api_key.deleted"` + - `vector_store_id: optional string` - - `"organization.project.api_key.deleted"` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -# Rate Limits + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -## List project rate limits + The aggregated web search calls usage details of the specific time bucket. -**get** `/organization/projects/{project_id}/rate_limits` + - `num_model_requests: number` -Returns the rate limits per model for a project. + The count of model requests. -### Path Parameters + - `num_requests: number` -- `project_id: string` + The count of web search calls. -### Query Parameters + - `object: "organization.usage.web_searches.result"` -- `after: optional string` + - `"organization.usage.web_searches.result"` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `api_key_id: optional string` -- `before: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, beginning with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `context_level: optional string` -- `limit: optional number` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - A limit on the number of objects to be returned. The default is 100. + - `model: optional string` -### Returns + When `group_by=model`, this field provides the model name of the grouped usage result. -- `data: array of ProjectRateLimit` + - `project_id: optional string` - - `id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - The identifier, which can be referenced in API endpoints. + - `user_id: optional string` - - `max_requests_per_1_minute: number` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - The maximum requests per minute. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `max_tokens_per_1_minute: number` + The aggregated costs details of the specific time bucket. - The maximum tokens per minute. + - `object: "organization.costs.result"` - - `model: string` + - `"organization.costs.result"` - The model this rate limit applies to. + - `amount: optional object { currency, value }` - - `object: "project.rate_limit"` + The monetary value in its associated currency. - The object type, which is always `project.rate_limit` + - `currency: optional string` - - `"project.rate_limit"` + Lowercase ISO-4217 currency e.g. "usd" - - `batch_1_day_max_input_tokens: optional number` + - `value: optional number` - The maximum batch input tokens per day. Only present for relevant models. + The numeric value of the cost. - - `max_audio_megabytes_per_1_minute: optional number` + - `api_key_id: optional string` - The maximum audio megabytes per minute. Only present for relevant models. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `max_images_per_1_minute: optional number` + - `line_item: optional string` - The maximum images per minute. Only present for relevant models. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `max_requests_per_1_day: optional number` + - `project_id: optional string` - The maximum requests per day. Only present for relevant models. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -- `has_more: boolean` + - `quantity: optional number` -- `object: "list"` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `"list"` + - `start_time: number` -- `first_id: optional string` + - `has_more: boolean` -- `last_id: optional string` + - `next_page: string` -### Example + - `object: "page"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/rate_limits \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"page"` -#### Response +### Usage File Search Calls Response -```json -{ - "data": [ - { - "id": "id", - "max_requests_per_1_minute": 0, - "max_tokens_per_1_minute": 0, - "model": "model", - "object": "project.rate_limit", - "batch_1_day_max_input_tokens": 0, - "max_audio_megabytes_per_1_minute": 0, - "max_images_per_1_minute": 0, - "max_requests_per_1_day": 0 - } - ], - "has_more": true, - "object": "list", - "first_id": "first_id", - "last_id": "last_id" -} -``` +- `UsageFileSearchCallsResponse object { data, has_more, next_page, object }` -### Example + - `data: array of object { end_time, object, results, start_time }` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `end_time: number` -#### Response + - `object: "bucket"` -```json -{ - "object": "list", - "data": [ - { - "object": "project.rate_limit", - "id": "rl-ada", - "model": "ada", - "max_requests_per_1_minute": 600, - "max_tokens_per_1_minute": 150000, - "max_images_per_1_minute": 10 - } - ], - "first_id": "rl-ada", - "last_id": "rl-ada", - "has_more": false -} -``` + - `"bucket"` -## Modify project rate limit + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -**post** `/organization/projects/{project_id}/rate_limits/{rate_limit_id}` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -Updates a project rate limit. + The aggregated completions usage details of the specific time bucket. -### Path Parameters + - `input_tokens: number` -- `project_id: string` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `rate_limit_id: string` + - `num_model_requests: number` -### Body Parameters + The count of requests made to the model. -- `batch_1_day_max_input_tokens: optional number` + - `object: "organization.usage.completions.result"` - The maximum batch input tokens per day. Only relevant for certain models. + - `"organization.usage.completions.result"` -- `max_audio_megabytes_per_1_minute: optional number` + - `output_tokens: number` - The maximum audio megabytes per minute. Only relevant for certain models. + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `max_images_per_1_minute: optional number` + - `api_key_id: optional string` - The maximum images per minute. Only relevant for certain models. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `max_requests_per_1_day: optional number` + - `batch: optional boolean` - The maximum requests per day. Only relevant for certain models. + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -- `max_requests_per_1_minute: optional number` + - `input_audio_tokens: optional number` - The maximum requests per minute. + The aggregated number of uncached audio input tokens used. -- `max_tokens_per_1_minute: optional number` + - `input_cache_write_tokens: optional number` - The maximum tokens per minute. + The aggregated number of input tokens written to the cache. -### Returns + - `input_cached_audio_tokens: optional number` -- `ProjectRateLimit object { id, max_requests_per_1_minute, max_tokens_per_1_minute, 6 more }` + The aggregated number of cached audio input tokens used. - Represents a project rate limit config. + - `input_cached_image_tokens: optional number` - - `id: string` + The aggregated number of cached image input tokens used. - The identifier, which can be referenced in API endpoints. + - `input_cached_text_tokens: optional number` - - `max_requests_per_1_minute: number` + The aggregated number of cached text input tokens used. - The maximum requests per minute. + - `input_cached_tokens: optional number` - - `max_tokens_per_1_minute: number` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The maximum tokens per minute. + - `input_image_tokens: optional number` - - `model: string` + The aggregated number of uncached image input tokens used. - The model this rate limit applies to. + - `input_text_tokens: optional number` - - `object: "project.rate_limit"` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - The object type, which is always `project.rate_limit` + - `input_uncached_tokens: optional number` - - `"project.rate_limit"` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `batch_1_day_max_input_tokens: optional number` + - `model: optional string` - The maximum batch input tokens per day. Only present for relevant models. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `max_audio_megabytes_per_1_minute: optional number` + - `output_audio_tokens: optional number` - The maximum audio megabytes per minute. Only present for relevant models. + The aggregated number of audio output tokens used. - - `max_images_per_1_minute: optional number` + - `output_image_tokens: optional number` - The maximum images per minute. Only present for relevant models. + The aggregated number of image output tokens used. - - `max_requests_per_1_day: optional number` + - `output_text_tokens: optional number` - The maximum requests per day. Only present for relevant models. + The aggregated number of text output tokens used. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/rate_limits/$RATE_LIMIT_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `service_tier: optional string` -```json -{ - "id": "id", - "max_requests_per_1_minute": 0, - "max_tokens_per_1_minute": 0, - "model": "model", - "object": "project.rate_limit", - "batch_1_day_max_input_tokens": 0, - "max_audio_megabytes_per_1_minute": 0, - "max_images_per_1_minute": 0, - "max_requests_per_1_day": 0 -} -``` + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -### Example + - `user_id: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "max_requests_per_1_minute": 500 - }' -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -#### Response + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -```json -{ - "object": "project.rate_limit", - "id": "rl-ada", - "model": "ada", - "max_requests_per_1_minute": 600, - "max_tokens_per_1_minute": 150000, - "max_images_per_1_minute": 10 - } -``` + The aggregated embeddings usage details of the specific time bucket. -## Domain Types + - `input_tokens: number` -### Project Rate Limit + The aggregated number of input tokens used. -- `ProjectRateLimit object { id, max_requests_per_1_minute, max_tokens_per_1_minute, 6 more }` + - `num_model_requests: number` - Represents a project rate limit config. + The count of requests made to the model. - - `id: string` + - `object: "organization.usage.embeddings.result"` - The identifier, which can be referenced in API endpoints. + - `"organization.usage.embeddings.result"` - - `max_requests_per_1_minute: number` + - `api_key_id: optional string` - The maximum requests per minute. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `max_tokens_per_1_minute: number` + - `model: optional string` - The maximum tokens per minute. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `model: string` + - `project_id: optional string` - The model this rate limit applies to. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `object: "project.rate_limit"` + - `user_id: optional string` - The object type, which is always `project.rate_limit` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"project.rate_limit"` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `batch_1_day_max_input_tokens: optional number` + The aggregated moderations usage details of the specific time bucket. - The maximum batch input tokens per day. Only present for relevant models. + - `input_tokens: number` - - `max_audio_megabytes_per_1_minute: optional number` + The aggregated number of input tokens used. - The maximum audio megabytes per minute. Only present for relevant models. + - `num_model_requests: number` - - `max_images_per_1_minute: optional number` + The count of requests made to the model. - The maximum images per minute. Only present for relevant models. + - `object: "organization.usage.moderations.result"` - - `max_requests_per_1_day: optional number` + - `"organization.usage.moderations.result"` - The maximum requests per day. Only present for relevant models. + - `api_key_id: optional string` -# Model Permissions + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -## Retrieve project model permissions + - `model: optional string` -**get** `/organization/projects/{project_id}/model_permissions` + When `group_by=model`, this field provides the model name of the grouped usage result. -Returns model permissions for a project. + - `project_id: optional string` -### Path Parameters + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `project_id: string` + - `user_id: optional string` -### Returns + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `ProjectModelPermissions object { mode, model_ids, object }` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - Represents the model allowlist or denylist policy for a project. + The aggregated images usage details of the specific time bucket. - - `mode: "allow_list" or "deny_list"` + - `images: number` - Whether the project uses an allowlist or a denylist. + The number of images processed. - - `"allow_list"` + - `num_model_requests: number` - - `"deny_list"` + The count of requests made to the model. - - `model_ids: array of string` + - `object: "organization.usage.images.result"` - The model IDs included in the model permissions policy. + - `"organization.usage.images.result"` - - `object: "project.model_permissions"` + - `api_key_id: optional string` - The object type, which is always `project.model_permissions`. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"project.model_permissions"` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "mode": "allow_list", - "model_ids": [ - "string" - ], - "object": "project.model_permissions" -} -``` + - `size: optional string` -### Example + When `group_by=size`, this field provides the image size of the grouped usage result. -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `source: optional string` -#### Response + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -```json -{ - "object": "project.model_permissions", - "mode": "allow_list", - "model_ids": [ - "gpt-4.1", - "o3" - ] -} -``` + - `user_id: optional string` -## Modify project model permissions + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -**post** `/organization/projects/{project_id}/model_permissions` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -Updates model permissions for a project. + The aggregated audio speeches usage details of the specific time bucket. -### Path Parameters + - `characters: number` -- `project_id: string` + The number of characters processed. -### Body Parameters + - `num_model_requests: number` -- `mode: "allow_list" or "deny_list"` + The count of requests made to the model. - The model permissions mode to apply. + - `object: "organization.usage.audio_speeches.result"` - - `"allow_list"` + - `"organization.usage.audio_speeches.result"` - - `"deny_list"` + - `api_key_id: optional string` -- `model_ids: array of string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The model IDs included in this permissions policy. + - `model: optional string` -### Returns + When `group_by=model`, this field provides the model name of the grouped usage result. -- `ProjectModelPermissions object { mode, model_ids, object }` + - `project_id: optional string` - Represents the model allowlist or denylist policy for a project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `mode: "allow_list" or "deny_list"` + - `user_id: optional string` - Whether the project uses an allowlist or a denylist. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"allow_list"` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `"deny_list"` + The aggregated audio transcriptions usage details of the specific time bucket. - - `model_ids: array of string` + - `num_model_requests: number` - The model IDs included in the model permissions policy. + The count of requests made to the model. - - `object: "project.model_permissions"` + - `object: "organization.usage.audio_transcriptions.result"` - The object type, which is always `project.model_permissions`. + - `"organization.usage.audio_transcriptions.result"` - - `"project.model_permissions"` + - `seconds: number` -### Example + The number of seconds processed. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "mode": "allow_list", - "model_ids": [ - "string" - ] - }' -``` + - `api_key_id: optional string` -#### Response + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```json -{ - "mode": "allow_list", - "model_ids": [ - "string" - ], - "object": "project.model_permissions" -} -``` + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "mode": "deny_list", - "model_ids": [ - "o3" - ] - }' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "object": "project.model_permissions", - "mode": "deny_list", - "model_ids": [ - "o3" - ] -} -``` + - `user_id: optional string` -## Delete project model permissions + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -**delete** `/organization/projects/{project_id}/model_permissions` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -Deletes model permissions for a project. + The aggregated vector stores usage details of the specific time bucket. -### Path Parameters + - `object: "organization.usage.vector_stores.result"` + + - `"organization.usage.vector_stores.result"` -- `project_id: string` + - `usage_bytes: number` -### Returns + The vector stores usage in bytes. -- `ProjectModelPermissionsDeleted object { deleted, object }` + - `project_id: optional string` - Confirmation payload returned after deleting project model permissions. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `deleted: boolean` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - Whether the project model permissions were deleted. + The aggregated code interpreter sessions usage details of the specific time bucket. - - `object: "project.model_permissions.deleted"` + - `num_sessions: number` - The object type, which is always `project.model_permissions.deleted`. + The number of code interpreter sessions. - - `"project.model_permissions.deleted"` + - `object: "organization.usage.code_interpreter_sessions.result"` -### Example + - `"organization.usage.code_interpreter_sessions.result"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/model_permissions \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "deleted": true, - "object": "project.model_permissions.deleted" -} -``` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -### Example + The aggregated file search calls usage details of the specific time bucket. -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `num_requests: number` -#### Response + The count of file search calls. -```json -{ - "object": "project.model_permissions.deleted", - "deleted": true -} -``` + - `object: "organization.usage.file_searches.result"` -## Domain Types + - `"organization.usage.file_searches.result"` -### Project Model Permissions + - `api_key_id: optional string` -- `ProjectModelPermissions object { mode, model_ids, object }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Represents the model allowlist or denylist policy for a project. + - `project_id: optional string` - - `mode: "allow_list" or "deny_list"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether the project uses an allowlist or a denylist. + - `user_id: optional string` - - `"allow_list"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"deny_list"` + - `vector_store_id: optional string` - - `model_ids: array of string` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. - The model IDs included in the model permissions policy. + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` - - `object: "project.model_permissions"` + The aggregated web search calls usage details of the specific time bucket. - The object type, which is always `project.model_permissions`. + - `num_model_requests: number` - - `"project.model_permissions"` + The count of model requests. -### Project Model Permissions Deleted + - `num_requests: number` -- `ProjectModelPermissionsDeleted object { deleted, object }` + The count of web search calls. - Confirmation payload returned after deleting project model permissions. + - `object: "organization.usage.web_searches.result"` - - `deleted: boolean` + - `"organization.usage.web_searches.result"` - Whether the project model permissions were deleted. + - `api_key_id: optional string` - - `object: "project.model_permissions.deleted"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The object type, which is always `project.model_permissions.deleted`. + - `context_level: optional string` - - `"project.model_permissions.deleted"` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -# Hosted Tool Permissions + - `model: optional string` -## Retrieve project hosted tool permissions + When `group_by=model`, this field provides the model name of the grouped usage result. -**get** `/organization/projects/{project_id}/hosted_tool_permissions` + - `project_id: optional string` -Returns hosted tool permissions for a project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Path Parameters + - `user_id: optional string` -- `project_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Returns + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` -- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` + The aggregated costs details of the specific time bucket. - Represents hosted tool permissions for a project. + - `object: "organization.costs.result"` - - `code_interpreter: object { enabled }` + - `"organization.costs.result"` - Permission state for a single hosted tool on a project. + - `amount: optional object { currency, value }` - - `enabled: boolean` + The monetary value in its associated currency. - Whether the hosted tool is enabled for the project. + - `currency: optional string` - - `file_search: object { enabled }` + Lowercase ISO-4217 currency e.g. "usd" - Permission state for a single hosted tool on a project. + - `value: optional number` - - `enabled: boolean` + The numeric value of the cost. - Whether the hosted tool is enabled for the project. + - `api_key_id: optional string` - - `image_generation: object { enabled }` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - Permission state for a single hosted tool on a project. + - `line_item: optional string` - - `enabled: boolean` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - Whether the hosted tool is enabled for the project. + - `project_id: optional string` - - `mcp: object { enabled }` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - Permission state for a single hosted tool on a project. + - `quantity: optional number` - - `enabled: boolean` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - Whether the hosted tool is enabled for the project. + - `start_time: number` - - `web_search: object { enabled }` + - `has_more: boolean` - Permission state for a single hosted tool on a project. + - `next_page: string` - - `enabled: boolean` + - `object: "page"` - Whether the hosted tool is enabled for the project. + - `"page"` -### Example +### Usage Images Response -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/hosted_tool_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` +- `UsageImagesResponse object { data, has_more, next_page, object }` -#### Response + - `data: array of object { end_time, object, results, start_time }` -```json -{ - "code_interpreter": { - "enabled": true - }, - "file_search": { - "enabled": true - }, - "image_generation": { - "enabled": true - }, - "mcp": { - "enabled": true - }, - "web_search": { - "enabled": true - } -} -``` + - `end_time: number` -### Example + - `object: "bucket"` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `"bucket"` -#### Response + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -```json -{ - "file_search": { - "enabled": true - }, - "web_search": { - "enabled": true - }, - "image_generation": { - "enabled": true - }, - "mcp": { - "enabled": true - }, - "code_interpreter": { - "enabled": true - } -} -``` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -## Modify project hosted tool permissions + The aggregated completions usage details of the specific time bucket. -**post** `/organization/projects/{project_id}/hosted_tool_permissions` + - `input_tokens: number` -Updates hosted tool permissions for a project. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Path Parameters + - `num_model_requests: number` -- `project_id: string` + The count of requests made to the model. -### Body Parameters + - `object: "organization.usage.completions.result"` -- `code_interpreter: optional object { enabled }` + - `"organization.usage.completions.result"` - The code interpreter permission update. + - `output_tokens: number` - - `enabled: boolean` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Whether to enable the hosted tool for the project. + - `api_key_id: optional string` -- `file_search: optional object { enabled }` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The file search permission update. + - `batch: optional boolean` - - `enabled: boolean` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - Whether to enable the hosted tool for the project. + - `input_audio_tokens: optional number` -- `image_generation: optional object { enabled }` + The aggregated number of uncached audio input tokens used. - The image generation permission update. + - `input_cache_write_tokens: optional number` - - `enabled: boolean` + The aggregated number of input tokens written to the cache. - Whether to enable the hosted tool for the project. + - `input_cached_audio_tokens: optional number` -- `mcp: optional object { enabled }` + The aggregated number of cached audio input tokens used. - The MCP permission update. + - `input_cached_image_tokens: optional number` - - `enabled: boolean` + The aggregated number of cached image input tokens used. - Whether to enable the hosted tool for the project. + - `input_cached_text_tokens: optional number` -- `web_search: optional object { enabled }` + The aggregated number of cached text input tokens used. - The web search permission update. + - `input_cached_tokens: optional number` - - `enabled: boolean` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Whether to enable the hosted tool for the project. + - `input_image_tokens: optional number` -### Returns + The aggregated number of uncached image input tokens used. -- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` + - `input_text_tokens: optional number` - Represents hosted tool permissions for a project. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `code_interpreter: object { enabled }` + - `input_uncached_tokens: optional number` - Permission state for a single hosted tool on a project. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `enabled: boolean` + - `model: optional string` - Whether the hosted tool is enabled for the project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `file_search: object { enabled }` + - `output_audio_tokens: optional number` - Permission state for a single hosted tool on a project. + The aggregated number of audio output tokens used. - - `enabled: boolean` + - `output_image_tokens: optional number` - Whether the hosted tool is enabled for the project. + The aggregated number of image output tokens used. - - `image_generation: object { enabled }` + - `output_text_tokens: optional number` - Permission state for a single hosted tool on a project. + The aggregated number of text output tokens used. - - `enabled: boolean` + - `project_id: optional string` - Whether the hosted tool is enabled for the project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `mcp: object { enabled }` + - `service_tier: optional string` - Permission state for a single hosted tool on a project. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `enabled: boolean` + - `user_id: optional string` - Whether the hosted tool is enabled for the project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `web_search: object { enabled }` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Permission state for a single hosted tool on a project. + The aggregated embeddings usage details of the specific time bucket. - - `enabled: boolean` + - `input_tokens: number` - Whether the hosted tool is enabled for the project. + The aggregated number of input tokens used. -### Example + - `num_model_requests: number` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/hosted_tool_permissions \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + The count of requests made to the model. -#### Response + - `object: "organization.usage.embeddings.result"` -```json -{ - "code_interpreter": { - "enabled": true - }, - "file_search": { - "enabled": true - }, - "image_generation": { - "enabled": true - }, - "mcp": { - "enabled": true - }, - "web_search": { - "enabled": true - } -} -``` + - `"organization.usage.embeddings.result"` -### Example + - `api_key_id: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "file_search": { - "enabled": true - }, - "image_generation": { - "enabled": false - } - }' -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "file_search": { - "enabled": true - }, - "web_search": { - "enabled": true - }, - "image_generation": { - "enabled": false - }, - "mcp": { - "enabled": true - }, - "code_interpreter": { - "enabled": true - } -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -## Domain Types + - `project_id: optional string` -### Project Hosted Tool Permissions + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `ProjectHostedToolPermissions object { code_interpreter, file_search, image_generation, 2 more }` + - `user_id: optional string` - Represents hosted tool permissions for a project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `code_interpreter: object { enabled }` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - Permission state for a single hosted tool on a project. + The aggregated moderations usage details of the specific time bucket. - - `enabled: boolean` + - `input_tokens: number` - Whether the hosted tool is enabled for the project. + The aggregated number of input tokens used. - - `file_search: object { enabled }` + - `num_model_requests: number` - Permission state for a single hosted tool on a project. + The count of requests made to the model. - - `enabled: boolean` + - `object: "organization.usage.moderations.result"` - Whether the hosted tool is enabled for the project. + - `"organization.usage.moderations.result"` - - `image_generation: object { enabled }` + - `api_key_id: optional string` - Permission state for a single hosted tool on a project. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `enabled: boolean` + - `model: optional string` - Whether the hosted tool is enabled for the project. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `mcp: object { enabled }` + - `project_id: optional string` - Permission state for a single hosted tool on a project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `enabled: boolean` + - `user_id: optional string` - Whether the hosted tool is enabled for the project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `web_search: object { enabled }` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - Permission state for a single hosted tool on a project. + The aggregated images usage details of the specific time bucket. - - `enabled: boolean` + - `images: number` - Whether the hosted tool is enabled for the project. + The number of images processed. -# Groups + - `num_model_requests: number` -## List project groups + The count of requests made to the model. -**get** `/organization/projects/{project_id}/groups` + - `object: "organization.usage.images.result"` -Lists the groups that have access to a project. + - `"organization.usage.images.result"` -### Path Parameters + - `api_key_id: optional string` -- `project_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Query Parameters + - `model: optional string` -- `after: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Cursor for pagination. Provide the ID of the last group from the previous response to fetch the next page. + - `project_id: optional string` -- `limit: optional number` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - A limit on the number of project groups to return. Defaults to 20. + - `size: optional string` -- `order: optional "asc" or "desc"` + When `group_by=size`, this field provides the image size of the grouped usage result. - Sort order for the returned groups. + - `source: optional string` - - `"asc"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - - `"desc"` + - `user_id: optional string` -### Returns + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `data: array of ProjectGroup` + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - Project group memberships returned in the current page. + The aggregated audio speeches usage details of the specific time bucket. - - `created_at: number` + - `characters: number` - Unix timestamp (in seconds) when the group was granted project access. + The number of characters processed. - - `group_id: string` + - `num_model_requests: number` - Identifier of the group that has access to the project. + The count of requests made to the model. - - `group_name: string` + - `object: "organization.usage.audio_speeches.result"` - Display name of the group. + - `"organization.usage.audio_speeches.result"` - - `group_type: "group" or "tenant_group"` + - `api_key_id: optional string` - The type of the group. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"group"` + - `model: optional string` - - `"tenant_group"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `object: "project.group"` + - `project_id: optional string` - Always `project.group`. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"project.group"` + - `user_id: optional string` - - `project_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Identifier of the project. + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` -- `has_more: boolean` + The aggregated audio transcriptions usage details of the specific time bucket. - Whether additional project group memberships are available. + - `num_model_requests: number` -- `next: string` + The count of requests made to the model. - Cursor to fetch the next page of results, or `null` when there are no more results. + - `object: "organization.usage.audio_transcriptions.result"` -- `object: "list"` + - `"organization.usage.audio_transcriptions.result"` - Always `list`. + - `seconds: number` - - `"list"` + The number of seconds processed. -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "data": [ - { - "created_at": 0, - "group_id": "group_id", - "group_name": "group_name", - "group_type": "group", - "object": "project.group", - "project_id": "project_id" - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc123/groups?limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "object": "list", - "data": [ - { - "object": "project.group", - "project_id": "proj_abc123", - "group_id": "group_01J1F8ABCDXYZ", - "group_name": "Support Team", - "created_at": 1711471533 - } - ], - "has_more": false, - "next": null -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -## Add project group + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -**post** `/organization/projects/{project_id}/groups` + The aggregated vector stores usage details of the specific time bucket. -Grants a group access to a project. + - `object: "organization.usage.vector_stores.result"` -### Path Parameters + - `"organization.usage.vector_stores.result"` -- `project_id: string` + - `usage_bytes: number` -### Body Parameters + The vector stores usage in bytes. -- `group_id: string` + - `project_id: optional string` - Identifier of the group to add to the project. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `role: string` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - Identifier of the project role to grant to the group. + The aggregated code interpreter sessions usage details of the specific time bucket. -### Returns + - `num_sessions: number` -- `ProjectGroup object { created_at, group_id, group_name, 3 more }` + The number of code interpreter sessions. - Details about a group's membership in a project. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `created_at: number` + - `"organization.usage.code_interpreter_sessions.result"` - Unix timestamp (in seconds) when the group was granted project access. + - `project_id: optional string` - - `group_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier of the group that has access to the project. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `group_name: string` + The aggregated file search calls usage details of the specific time bucket. - Display name of the group. + - `num_requests: number` - - `group_type: "group" or "tenant_group"` + The count of file search calls. - The type of the group. + - `object: "organization.usage.file_searches.result"` - - `"group"` + - `"organization.usage.file_searches.result"` - - `"tenant_group"` + - `api_key_id: optional string` - - `object: "project.group"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Always `project.group`. + - `project_id: optional string` - - `"project.group"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `project_id: string` + - `user_id: optional string` - Identifier of the project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `vector_store_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "group_id": "group_id", - "role": "role" - }' -``` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -#### Response + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -```json -{ - "created_at": 0, - "group_id": "group_id", - "group_name": "group_name", - "group_type": "group", - "object": "project.group", - "project_id": "project_id" -} -``` + The aggregated web search calls usage details of the specific time bucket. -### Example + - `num_model_requests: number` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc123/groups \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "group_id": "group_01J1F8ABCDXYZ", - "role": "role_01J1F8PROJ" - }' -``` + The count of model requests. -#### Response + - `num_requests: number` -```json -{ - "object": "project.group", - "project_id": "proj_abc123", - "group_id": "group_01J1F8ABCDXYZ", - "group_name": "Support Team", - "created_at": 1711471533 -} -``` + The count of web search calls. -## Retrieve project group + - `object: "organization.usage.web_searches.result"` -**get** `/organization/projects/{project_id}/groups/{group_id}` + - `"organization.usage.web_searches.result"` -Retrieves a project's group. + - `api_key_id: optional string` -### Path Parameters + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `project_id: string` + - `context_level: optional string` -- `group_id: string` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -### Query Parameters + - `model: optional string` -- `group_type: optional "group" or "tenant_group"` + When `group_by=model`, this field provides the model name of the grouped usage result. - The type of group to retrieve. + - `project_id: optional string` - - `"group"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"tenant_group"` + - `user_id: optional string` -### Returns + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `ProjectGroup object { created_at, group_id, group_name, 3 more }` + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - Details about a group's membership in a project. + The aggregated costs details of the specific time bucket. - - `created_at: number` + - `object: "organization.costs.result"` - Unix timestamp (in seconds) when the group was granted project access. + - `"organization.costs.result"` - - `group_id: string` + - `amount: optional object { currency, value }` - Identifier of the group that has access to the project. + The monetary value in its associated currency. - - `group_name: string` + - `currency: optional string` - Display name of the group. + Lowercase ISO-4217 currency e.g. "usd" - - `group_type: "group" or "tenant_group"` + - `value: optional number` - The type of the group. + The numeric value of the cost. - - `"group"` + - `api_key_id: optional string` - - `"tenant_group"` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `object: "project.group"` + - `line_item: optional string` - Always `project.group`. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `"project.group"` + - `project_id: optional string` - - `project_id: string` + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - Identifier of the project. + - `quantity: optional number` -### Example + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups/$GROUP_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `start_time: number` -#### Response + - `has_more: boolean` -```json -{ - "created_at": 0, - "group_id": "group_id", - "group_name": "group_name", - "group_type": "group", - "object": "project.group", - "project_id": "project_id" -} -``` + - `next_page: string` -### Example + - `object: "page"` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `"page"` -#### Response +### Usage Moderations Response -```json -{ - "object": "project.group", - "project_id": "proj_abc123", - "group_id": "group_01J1F8ABCDXYZ", - "group_name": "Support Team", - "group_type": "group", - "created_at": 1711471533 -} -``` +- `UsageModerationsResponse object { data, has_more, next_page, object }` -## Remove project group + - `data: array of object { end_time, object, results, start_time }` -**delete** `/organization/projects/{project_id}/groups/{group_id}` + - `end_time: number` -Revokes a group's access to a project. + - `object: "bucket"` -### Path Parameters + - `"bucket"` -- `project_id: string` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -- `group_id: string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -### Returns + The aggregated completions usage details of the specific time bucket. -- `deleted: boolean` + - `input_tokens: number` - Whether the group membership in the project was removed. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `object: "project.group.deleted"` + - `num_model_requests: number` - Always `project.group.deleted`. + The count of requests made to the model. - - `"project.group.deleted"` + - `object: "organization.usage.completions.result"` -### Example + - `"organization.usage.completions.result"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/groups/$GROUP_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `output_tokens: number` -#### Response + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -```json -{ - "deleted": true, - "object": "project.group.deleted" -} -``` + - `api_key_id: optional string` -### Example + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `batch: optional boolean` -#### Response + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -```json -{ - "object": "project.group.deleted", - "deleted": true -} -``` + - `input_audio_tokens: optional number` -## Domain Types + The aggregated number of uncached audio input tokens used. -### Project Group + - `input_cache_write_tokens: optional number` -- `ProjectGroup object { created_at, group_id, group_name, 3 more }` + The aggregated number of input tokens written to the cache. - Details about a group's membership in a project. + - `input_cached_audio_tokens: optional number` - - `created_at: number` + The aggregated number of cached audio input tokens used. - Unix timestamp (in seconds) when the group was granted project access. + - `input_cached_image_tokens: optional number` - - `group_id: string` + The aggregated number of cached image input tokens used. - Identifier of the group that has access to the project. + - `input_cached_text_tokens: optional number` - - `group_name: string` + The aggregated number of cached text input tokens used. - Display name of the group. + - `input_cached_tokens: optional number` - - `group_type: "group" or "tenant_group"` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - The type of the group. + - `input_image_tokens: optional number` - - `"group"` + The aggregated number of uncached image input tokens used. - - `"tenant_group"` + - `input_text_tokens: optional number` - - `object: "project.group"` + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - Always `project.group`. + - `input_uncached_tokens: optional number` - - `"project.group"` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `project_id: string` + - `model: optional string` - Identifier of the project. + When `group_by=model`, this field provides the model name of the grouped usage result. -### Group Delete Response + - `output_audio_tokens: optional number` -- `GroupDeleteResponse object { deleted, object }` + The aggregated number of audio output tokens used. - Confirmation payload returned after removing a group from a project. + - `output_image_tokens: optional number` - - `deleted: boolean` + The aggregated number of image output tokens used. - Whether the group membership in the project was removed. + - `output_text_tokens: optional number` - - `object: "project.group.deleted"` + The aggregated number of text output tokens used. - Always `project.group.deleted`. + - `project_id: optional string` - - `"project.group.deleted"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -# Roles + - `service_tier: optional string` -## List project group role assignments + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -**get** `/projects/{project_id}/groups/{group_id}/roles` + - `user_id: optional string` -Lists the project roles assigned to a group within a project. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Path Parameters + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` -- `project_id: string` + The aggregated embeddings usage details of the specific time bucket. -- `group_id: string` + - `input_tokens: number` -### Query Parameters + The aggregated number of input tokens used. -- `after: optional string` + - `num_model_requests: number` - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles. + The count of requests made to the model. -- `limit: optional number` + - `object: "organization.usage.embeddings.result"` - A limit on the number of project role assignments to return. + - `"organization.usage.embeddings.result"` -- `order: optional "asc" or "desc"` + - `api_key_id: optional string` - Sort order for the returned project roles. + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `"asc"` + - `model: optional string` - - `"desc"` + When `group_by=model`, this field provides the model name of the grouped usage result. -### Returns + - `project_id: optional string` -- `data: array of object { id, assignment_sources, created_at, 9 more }` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Role assignments returned in the current page. + - `user_id: optional string` - - `id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Identifier for the role. + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `assignment_sources: array of object { principal_id, principal_type }` + The aggregated moderations usage details of the specific time bucket. - Principals from which the role assignment is inherited, when available. + - `input_tokens: number` - - `principal_id: string` + The aggregated number of input tokens used. - - `principal_type: string` + - `num_model_requests: number` - - `created_at: number` + The count of requests made to the model. - When the role was created. + - `object: "organization.usage.moderations.result"` - - `created_by: string` + - `"organization.usage.moderations.result"` - Identifier of the actor who created the role. + - `api_key_id: optional string` - - `created_by_user_obj: map[unknown]` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - User details for the actor that created the role, when available. + - `model: optional string` - - `description: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Description of the role. + - `project_id: optional string` - - `metadata: map[unknown]` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Arbitrary metadata stored on the role. + - `user_id: optional string` - - `name: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Name of the role. + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - - `permissions: array of string` + The aggregated images usage details of the specific time bucket. - Permissions associated with the role. + - `images: number` - - `predefined_role: boolean` + The number of images processed. - Whether the role is predefined by OpenAI. + - `num_model_requests: number` - - `resource_type: string` + The count of requests made to the model. - Resource type the role applies to. + - `object: "organization.usage.images.result"` - - `updated_at: number` + - `"organization.usage.images.result"` - When the role was last updated. + - `api_key_id: optional string` -- `has_more: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether additional assignments are available when paginating. + - `model: optional string` -- `next: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Cursor to fetch the next page of results, or `null` when there are no more assignments. + - `project_id: optional string` -- `object: "list"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Always `list`. + - `size: optional string` - - `"list"` + When `group_by=size`, this field provides the image size of the grouped usage result. -### Example + - `source: optional string` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. -#### Response + - `user_id: optional string` -```json -{ - "data": [ - { - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -```http -curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated audio speeches usage details of the specific time bucket. -#### Response + - `characters: number` -```json -{ - "object": "list", - "data": [ - { - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false, - "description": "Allows managing API keys for the project", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": { - "id": "user_abc123", - "name": "Ada Lovelace", - "email": "ada@example.com" - }, - "metadata": {} - } - ], - "has_more": false, - "next": null -} -``` + The number of characters processed. -## Assign project role to group + - `num_model_requests: number` -**post** `/projects/{project_id}/groups/{group_id}/roles` + The count of requests made to the model. -Assigns a project role to a group within a project. + - `object: "organization.usage.audio_speeches.result"` -### Path Parameters + - `"organization.usage.audio_speeches.result"` -- `project_id: string` + - `api_key_id: optional string` -- `group_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Body Parameters + - `model: optional string` -- `role_id: string` + When `group_by=model`, this field provides the model name of the grouped usage result. - Identifier of the role to assign. + - `project_id: optional string` -### Returns + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `group: object { id, created_at, name, 2 more }` + - `user_id: optional string` - Summary information about a group returned in role assignment responses. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - Identifier for the group. + The aggregated audio transcriptions usage details of the specific time bucket. - - `created_at: number` + - `num_model_requests: number` - Unix timestamp (in seconds) when the group was created. + The count of requests made to the model. - - `name: string` + - `object: "organization.usage.audio_transcriptions.result"` - Display name of the group. + - `"organization.usage.audio_transcriptions.result"` - - `object: "group"` + - `seconds: number` - Always `group`. + The number of seconds processed. - - `"group"` + - `api_key_id: optional string` - - `scim_managed: boolean` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Whether the group is managed through SCIM. + - `model: optional string` -- `object: "group.role"` + When `group_by=model`, this field provides the model name of the grouped usage result. - Always `group.role`. + - `project_id: optional string` - - `"group.role"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `role: Role` + - `user_id: optional string` - Details about a role that can be assigned through the public Roles API. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `id: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` - Identifier for the role. + The aggregated vector stores usage details of the specific time bucket. - - `description: string` + - `object: "organization.usage.vector_stores.result"` - Optional description of the role. + - `"organization.usage.vector_stores.result"` - - `name: string` + - `usage_bytes: number` - Unique name for the role. + The vector stores usage in bytes. - - `object: "role"` + - `project_id: optional string` - Always `role`. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"role"` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - - `permissions: array of string` + The aggregated code interpreter sessions usage details of the specific time bucket. - Permissions granted by the role. + - `num_sessions: number` - - `predefined_role: boolean` + The number of code interpreter sessions. - Whether the role is predefined and managed by OpenAI. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `resource_type: string` + - `"organization.usage.code_interpreter_sessions.result"` - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `project_id: optional string` -### Example + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "role_id": "role_id" - }' -``` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` -#### Response + The aggregated file search calls usage details of the specific time bucket. -```json -{ - "group": { - "id": "id", - "created_at": 0, - "name": "name", - "object": "group", - "scim_managed": true - }, - "object": "group.role", - "role": { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" - } -} -``` + - `num_requests: number` -### Example + The count of file search calls. -```http -curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_id": "role_01J1F8PROJ" - }' -``` + - `object: "organization.usage.file_searches.result"` -#### Response + - `"organization.usage.file_searches.result"` -```json -{ - "object": "group.role", - "group": { - "object": "group", - "id": "group_01J1F8ABCDXYZ", - "name": "Support Team", - "created_at": 1711471533, - "scim_managed": false - }, - "role": { - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false - } -} -``` + - `api_key_id: optional string` -## Retrieve project group role + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -**get** `/projects/{project_id}/groups/{group_id}/roles/{role_id}` + - `project_id: optional string` -Retrieves a project role assigned to a group. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Path Parameters + - `user_id: optional string` -- `project_id: string` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `group_id: string` + - `vector_store_id: optional string` -- `role_id: string` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -### Returns + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -- `id: string` + The aggregated web search calls usage details of the specific time bucket. - Identifier for the role. + - `num_model_requests: number` -- `assignment_sources: array of object { principal_id, principal_type }` + The count of model requests. - Principals from which the role assignment is inherited, when available. + - `num_requests: number` - - `principal_id: string` + The count of web search calls. - - `principal_type: string` + - `object: "organization.usage.web_searches.result"` -- `created_at: number` + - `"organization.usage.web_searches.result"` - When the role was created. + - `api_key_id: optional string` -- `created_by: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Identifier of the actor who created the role. + - `context_level: optional string` -- `created_by_user_obj: map[unknown]` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - User details for the actor that created the role, when available. + - `model: optional string` -- `description: string` + When `group_by=model`, this field provides the model name of the grouped usage result. + + - `project_id: optional string` + + When `group_by=project_id`, this field provides the project ID of the grouped usage result. + + - `user_id: optional string` + + When `group_by=user_id`, this field provides the user ID of the grouped usage result. + + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` + + The aggregated costs details of the specific time bucket. + + - `object: "organization.costs.result"` - Description of the role. + - `"organization.costs.result"` -- `metadata: map[unknown]` + - `amount: optional object { currency, value }` - Arbitrary metadata stored on the role. + The monetary value in its associated currency. -- `name: string` + - `currency: optional string` - Name of the role. + Lowercase ISO-4217 currency e.g. "usd" -- `permissions: array of string` + - `value: optional number` - Permissions associated with the role. + The numeric value of the cost. -- `predefined_role: boolean` + - `api_key_id: optional string` - Whether the role is predefined by OpenAI. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. -- `resource_type: string` + - `line_item: optional string` - Resource type the role applies to. + When `group_by=line_item`, this field provides the line item of the grouped costs result. -- `updated_at: number` + - `project_id: optional string` - When the role was last updated. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -### Example + - `quantity: optional number` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -#### Response + - `start_time: number` -```json -{ - "id": "id", - "assignment_sources": [ - { - "principal_id": "principal_id", - "principal_type": "principal_type" - } - ], - "created_at": 0, - "created_by": "created_by", - "created_by_user_obj": { - "foo": "bar" - }, - "description": "description", - "metadata": { - "foo": "bar" - }, - "name": "name", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type", - "updated_at": 0 -} -``` + - `has_more: boolean` -### Example + - `next_page: string` -```http -curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `object: "page"` -#### Response + - `"page"` -```json -{ - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false, - "description": "Allows managing API keys for the project", - "created_at": 1711471533, - "updated_at": 1711472599, - "created_by": "user_abc123", - "created_by_user_obj": null, - "metadata": {}, - "assignment_sources": null -} -``` +### Usage Vector Stores Response -## Unassign project role from group +- `UsageVectorStoresResponse object { data, has_more, next_page, object }` -**delete** `/projects/{project_id}/groups/{group_id}/roles/{role_id}` + - `data: array of object { end_time, object, results, start_time }` -Unassigns a project role from a group within a project. + - `end_time: number` -### Path Parameters + - `object: "bucket"` -- `project_id: string` + - `"bucket"` -- `group_id: string` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -- `role_id: string` + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -### Returns + The aggregated completions usage details of the specific time bucket. -- `deleted: boolean` + - `input_tokens: number` - Whether the assignment was removed. + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -- `object: string` + - `num_model_requests: number` - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + The count of requests made to the model. -### Example + - `object: "organization.usage.completions.result"` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/groups/$GROUP_ID/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.usage.completions.result"` -#### Response + - `output_tokens: number` -```json -{ - "deleted": true, - "object": "object" -} -``` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -### Example + - `api_key_id: optional string` -```http -curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `batch: optional boolean` -```json -{ - "object": "group.role.deleted", - "deleted": true -} -``` + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. -## Domain Types + - `input_audio_tokens: optional number` -### Role List Response + The aggregated number of uncached audio input tokens used. -- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` + - `input_cache_write_tokens: optional number` - Detailed information about a role assignment entry returned when listing assignments. + The aggregated number of input tokens written to the cache. - - `id: string` + - `input_cached_audio_tokens: optional number` - Identifier for the role. + The aggregated number of cached audio input tokens used. - - `assignment_sources: array of object { principal_id, principal_type }` + - `input_cached_image_tokens: optional number` - Principals from which the role assignment is inherited, when available. + The aggregated number of cached image input tokens used. - - `principal_id: string` + - `input_cached_text_tokens: optional number` - - `principal_type: string` + The aggregated number of cached text input tokens used. - - `created_at: number` + - `input_cached_tokens: optional number` - When the role was created. + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - - `created_by: string` + - `input_image_tokens: optional number` - Identifier of the actor who created the role. + The aggregated number of uncached image input tokens used. - - `created_by_user_obj: map[unknown]` + - `input_text_tokens: optional number` - User details for the actor that created the role, when available. + The aggregated number of uncached text input tokens used, excluding cache-write tokens. - - `description: string` + - `input_uncached_tokens: optional number` - Description of the role. + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. - - `metadata: map[unknown]` + - `model: optional string` - Arbitrary metadata stored on the role. + When `group_by=model`, this field provides the model name of the grouped usage result. - - `name: string` + - `output_audio_tokens: optional number` - Name of the role. + The aggregated number of audio output tokens used. - - `permissions: array of string` + - `output_image_tokens: optional number` - Permissions associated with the role. + The aggregated number of image output tokens used. - - `predefined_role: boolean` + - `output_text_tokens: optional number` - Whether the role is predefined by OpenAI. + The aggregated number of text output tokens used. - - `resource_type: string` + - `project_id: optional string` - Resource type the role applies to. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `updated_at: number` + - `service_tier: optional string` - When the role was last updated. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. -### Role Create Response + - `user_id: optional string` -- `RoleCreateResponse object { group, object, role }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Role assignment linking a group to a role. + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - - `group: object { id, created_at, name, 2 more }` + The aggregated embeddings usage details of the specific time bucket. - Summary information about a group returned in role assignment responses. + - `input_tokens: number` - - `id: string` + The aggregated number of input tokens used. - Identifier for the group. + - `num_model_requests: number` - - `created_at: number` + The count of requests made to the model. - Unix timestamp (in seconds) when the group was created. + - `object: "organization.usage.embeddings.result"` - - `name: string` + - `"organization.usage.embeddings.result"` - Display name of the group. + - `api_key_id: optional string` - - `object: "group"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Always `group`. + - `model: optional string` - - `"group"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `scim_managed: boolean` + - `project_id: optional string` - Whether the group is managed through SCIM. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `object: "group.role"` + - `user_id: optional string` - Always `group.role`. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"group.role"` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` - - `role: Role` + The aggregated moderations usage details of the specific time bucket. - Details about a role that can be assigned through the public Roles API. + - `input_tokens: number` - - `id: string` + The aggregated number of input tokens used. - Identifier for the role. + - `num_model_requests: number` - - `description: string` + The count of requests made to the model. - Optional description of the role. + - `object: "organization.usage.moderations.result"` - - `name: string` + - `"organization.usage.moderations.result"` - Unique name for the role. + - `api_key_id: optional string` - - `object: "role"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Always `role`. + - `model: optional string` - - `"role"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `permissions: array of string` + - `project_id: optional string` - Permissions granted by the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `predefined_role: boolean` + - `user_id: optional string` - Whether the role is predefined and managed by OpenAI. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `resource_type: string` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` - Resource type the role is bound to (for example `api.organization` or `api.project`). + The aggregated images usage details of the specific time bucket. -### Role Retrieve Response + - `images: number` -- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` + The number of images processed. - Detailed information about a role assignment entry returned when listing assignments. + - `num_model_requests: number` - - `id: string` + The count of requests made to the model. - Identifier for the role. + - `object: "organization.usage.images.result"` - - `assignment_sources: array of object { principal_id, principal_type }` + - `"organization.usage.images.result"` - Principals from which the role assignment is inherited, when available. + - `api_key_id: optional string` - - `principal_id: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `principal_type: string` + - `model: optional string` - - `created_at: number` + When `group_by=model`, this field provides the model name of the grouped usage result. - When the role was created. + - `project_id: optional string` - - `created_by: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier of the actor who created the role. + - `size: optional string` - - `created_by_user_obj: map[unknown]` + When `group_by=size`, this field provides the image size of the grouped usage result. - User details for the actor that created the role, when available. + - `source: optional string` - - `description: string` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - Description of the role. + - `user_id: optional string` - - `metadata: map[unknown]` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Arbitrary metadata stored on the role. + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` - - `name: string` + The aggregated audio speeches usage details of the specific time bucket. - Name of the role. + - `characters: number` - - `permissions: array of string` + The number of characters processed. - Permissions associated with the role. + - `num_model_requests: number` - - `predefined_role: boolean` + The count of requests made to the model. - Whether the role is predefined by OpenAI. + - `object: "organization.usage.audio_speeches.result"` - - `resource_type: string` + - `"organization.usage.audio_speeches.result"` - Resource type the role applies to. + - `api_key_id: optional string` - - `updated_at: number` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - When the role was last updated. + - `model: optional string` -### Role Delete Response + When `group_by=model`, this field provides the model name of the grouped usage result. -- `RoleDeleteResponse object { deleted, object }` + - `project_id: optional string` - Confirmation payload returned after unassigning a role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `deleted: boolean` + - `user_id: optional string` - Whether the assignment was removed. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `object: string` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. + The aggregated audio transcriptions usage details of the specific time bucket. -# Roles + - `num_model_requests: number` -## List project roles + The count of requests made to the model. -**get** `/projects/{project_id}/roles` + - `object: "organization.usage.audio_transcriptions.result"` -Lists the roles configured for a project. + - `"organization.usage.audio_transcriptions.result"` -### Path Parameters + - `seconds: number` -- `project_id: string` + The number of seconds processed. -### Query Parameters + - `api_key_id: optional string` -- `after: optional string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles. + - `model: optional string` -- `limit: optional number` + When `group_by=model`, this field provides the model name of the grouped usage result. - A limit on the number of roles to return. Defaults to 1000. + - `project_id: optional string` -- `order: optional "asc" or "desc"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Sort order for the returned roles. + - `user_id: optional string` - - `"asc"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"desc"` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -### Returns + The aggregated vector stores usage details of the specific time bucket. -- `data: array of Role` + - `object: "organization.usage.vector_stores.result"` - Roles returned in the current page. + - `"organization.usage.vector_stores.result"` - - `id: string` + - `usage_bytes: number` - Identifier for the role. + The vector stores usage in bytes. - - `description: string` + - `project_id: optional string` - Optional description of the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `name: string` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - Unique name for the role. + The aggregated code interpreter sessions usage details of the specific time bucket. - - `object: "role"` + - `num_sessions: number` - Always `role`. + The number of code interpreter sessions. - - `"role"` + - `object: "organization.usage.code_interpreter_sessions.result"` - - `permissions: array of string` + - `"organization.usage.code_interpreter_sessions.result"` - Permissions granted by the role. + - `project_id: optional string` - - `predefined_role: boolean` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Whether the role is predefined and managed by OpenAI. + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - - `resource_type: string` + The aggregated file search calls usage details of the specific time bucket. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `num_requests: number` -- `has_more: boolean` + The count of file search calls. - Whether more roles are available when paginating. + - `object: "organization.usage.file_searches.result"` -- `next: string` + - `"organization.usage.file_searches.result"` - Cursor to fetch the next page of results, or `null` when there are no additional roles. + - `api_key_id: optional string` -- `object: "list"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Always `list`. + - `project_id: optional string` - - `"list"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Example + - `user_id: optional string` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -#### Response + - `vector_store_id: optional string` -```json -{ - "data": [ - { - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" - } - ], - "has_more": true, - "next": "next", - "object": "list" -} -``` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -### Example + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -```http -curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated web search calls usage details of the specific time bucket. -#### Response + - `num_model_requests: number` -```json -{ - "object": "list", - "data": [ - { - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false - } - ], - "has_more": false, - "next": null -} -``` + The count of model requests. -## Create project role + - `num_requests: number` -**post** `/projects/{project_id}/roles` + The count of web search calls. -Creates a custom role for a project. + - `object: "organization.usage.web_searches.result"` -### Path Parameters + - `"organization.usage.web_searches.result"` -- `project_id: string` + - `api_key_id: optional string` -### Body Parameters + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `permissions: array of string` + - `context_level: optional string` - Permissions to grant to the role. + When `group_by=context_level`, this field provides the search context size of the grouped usage result. -- `role_name: string` + - `model: optional string` - Unique name for the role. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `description: optional string` + - `project_id: optional string` - Optional description of the role. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -### Returns + - `user_id: optional string` -- `Role object { id, description, name, 4 more }` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - Details about a role that can be assigned through the public Roles API. + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` - - `id: string` + The aggregated costs details of the specific time bucket. - Identifier for the role. + - `object: "organization.costs.result"` - - `description: string` + - `"organization.costs.result"` - Optional description of the role. + - `amount: optional object { currency, value }` - - `name: string` + The monetary value in its associated currency. - Unique name for the role. + - `currency: optional string` - - `object: "role"` + Lowercase ISO-4217 currency e.g. "usd" - Always `role`. + - `value: optional number` - - `"role"` + The numeric value of the cost. - - `permissions: array of string` + - `api_key_id: optional string` - Permissions granted by the role. + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - - `predefined_role: boolean` + - `line_item: optional string` - Whether the role is predefined and managed by OpenAI. + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `resource_type: string` + - `project_id: optional string` - Resource type the role is bound to (for example `api.organization` or `api.project`). + When `group_by=project_id`, this field provides the project ID of the grouped costs result. -### Example + - `quantity: optional number` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/roles \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "permissions": [ - "string" - ], - "role_name": "role_name" - }' -``` + When `group_by=line_item`, this field provides the quantity of the grouped costs result. -#### Response + - `start_time: number` -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + - `has_more: boolean` -### Example + - `next_page: string` -```http -curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "description": "Allows managing API keys for the project" - }' -``` + - `object: "page"` -#### Response + - `"page"` -```json -{ - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false -} -``` +### Usage Web Search Calls Response -## Retrieve project role +- `UsageWebSearchCallsResponse object { data, has_more, next_page, object }` -**get** `/projects/{project_id}/roles/{role_id}` + - `data: array of object { end_time, object, results, start_time }` -Retrieves a project role. + - `end_time: number` -### Path Parameters + - `object: "bucket"` -- `project_id: string` + - `"bucket"` -- `role_id: string` + - `results: array of object { input_tokens, num_model_requests, object, 19 more } or object { input_tokens, num_model_requests, object, 4 more } or object { input_tokens, num_model_requests, object, 4 more } or 8 more` -### Returns + - `OrganizationUsageCompletionsResult object { input_tokens, num_model_requests, object, 19 more }` -- `Role object { id, description, name, 4 more }` + The aggregated completions usage details of the specific time bucket. - Details about a role that can be assigned through the public Roles API. + - `input_tokens: number` - - `id: string` + The aggregated number of input tokens used, including cached and cache-write tokens. This includes text, audio, and image tokens. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Identifier for the role. + - `num_model_requests: number` - - `description: string` + The count of requests made to the model. - Optional description of the role. + - `object: "organization.usage.completions.result"` - - `name: string` + - `"organization.usage.completions.result"` - Unique name for the role. + - `output_tokens: number` - - `object: "role"` + The aggregated number of output tokens used across text, audio, and image outputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. - Always `role`. + - `api_key_id: optional string` - - `"role"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - - `permissions: array of string` + - `batch: optional boolean` - Permissions granted by the role. + When `group_by=batch`, this field tells whether the grouped usage result is batch or not. - - `predefined_role: boolean` + - `input_audio_tokens: optional number` - Whether the role is predefined and managed by OpenAI. + The aggregated number of uncached audio input tokens used. - - `resource_type: string` + - `input_cache_write_tokens: optional number` - Resource type the role is bound to (for example `api.organization` or `api.project`). + The aggregated number of input tokens written to the cache. -### Example + - `input_cached_audio_tokens: optional number` -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + The aggregated number of cached audio input tokens used. -#### Response + - `input_cached_image_tokens: optional number` -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + The aggregated number of cached image input tokens used. -### Example + - `input_cached_text_tokens: optional number` -```http -curl https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The aggregated number of cached text input tokens used. -#### Response + - `input_cached_tokens: optional number` -```json -{ - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false -} -``` + The aggregated number of cached input tokens used across text, audio, and image inputs. For customers subscribed to Scale Tier, this includes Scale Tier tokens. -## Update project role + - `input_image_tokens: optional number` -**post** `/projects/{project_id}/roles/{role_id}` + The aggregated number of uncached image input tokens used. -Updates an existing project role. + - `input_text_tokens: optional number` -### Path Parameters + The aggregated number of uncached text input tokens used, excluding cache-write tokens. -- `project_id: string` + - `input_uncached_tokens: optional number` -- `role_id: string` + The aggregated number of uncached input tokens used across text, audio, and image inputs, excluding cache-write tokens. -### Body Parameters + - `model: optional string` -- `description: optional string` + When `group_by=model`, this field provides the model name of the grouped usage result. - New description for the role. + - `output_audio_tokens: optional number` -- `permissions: optional array of string` + The aggregated number of audio output tokens used. - Updated set of permissions for the role. + - `output_image_tokens: optional number` -- `role_name: optional string` + The aggregated number of image output tokens used. - New name for the role. + - `output_text_tokens: optional number` -### Returns + The aggregated number of text output tokens used. -- `Role object { id, description, name, 4 more }` + - `project_id: optional string` - Details about a role that can be assigned through the public Roles API. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `id: string` + - `service_tier: optional string` - Identifier for the role. + When `group_by=service_tier`, this field provides the service tier of the grouped usage result. - - `description: string` + - `user_id: optional string` - Optional description of the role. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `name: string` + - `OrganizationUsageEmbeddingsResult object { input_tokens, num_model_requests, object, 4 more }` - Unique name for the role. + The aggregated embeddings usage details of the specific time bucket. - - `object: "role"` + - `input_tokens: number` - Always `role`. + The aggregated number of input tokens used. - - `"role"` + - `num_model_requests: number` - - `permissions: array of string` + The count of requests made to the model. - Permissions granted by the role. + - `object: "organization.usage.embeddings.result"` - - `predefined_role: boolean` + - `"organization.usage.embeddings.result"` - Whether the role is predefined and managed by OpenAI. + - `api_key_id: optional string` - - `resource_type: string` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - Resource type the role is bound to (for example `api.organization` or `api.project`). + - `model: optional string` -### Example + When `group_by=model`, this field provides the model name of the grouped usage result. -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{}' -``` + - `project_id: optional string` -#### Response + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -```json -{ - "id": "id", - "description": "description", - "name": "name", - "object": "role", - "permissions": [ - "string" - ], - "predefined_role": true, - "resource_type": "resource_type" -} -``` + - `user_id: optional string` -### Example + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -```http -curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role_name": "API Project Key Manager", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "description": "Allows managing API keys for the project" - }' -``` + - `OrganizationUsageModerationsResult object { input_tokens, num_model_requests, object, 4 more }` -#### Response + The aggregated moderations usage details of the specific time bucket. -```json -{ - "object": "role", - "id": "role_01J1F8PROJ", - "name": "API Project Key Manager", - "description": "Allows managing API keys for the project", - "permissions": [ - "api.organization.projects.api_keys.read", - "api.organization.projects.api_keys.write" - ], - "resource_type": "api.project", - "predefined_role": false -} -``` + - `input_tokens: number` -## Delete project role + The aggregated number of input tokens used. -**delete** `/projects/{project_id}/roles/{role_id}` + - `num_model_requests: number` -Deletes a custom role from a project. + The count of requests made to the model. -### Path Parameters + - `object: "organization.usage.moderations.result"` -- `project_id: string` + - `"organization.usage.moderations.result"` -- `role_id: string` + - `api_key_id: optional string` -### Returns + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -- `id: string` + - `model: optional string` - Identifier of the deleted role. + When `group_by=model`, this field provides the model name of the grouped usage result. -- `deleted: boolean` + - `project_id: optional string` - Whether the role was deleted. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -- `object: "role.deleted"` + - `user_id: optional string` - Always `role.deleted`. + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"role.deleted"` + - `OrganizationUsageImagesResult object { images, num_model_requests, object, 6 more }` -### Example + The aggregated images usage details of the specific time bucket. -```http -curl https://api.openai.com/v1/projects/$PROJECT_ID/roles/$ROLE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `images: number` -#### Response + The number of images processed. -```json -{ - "id": "id", - "deleted": true, - "object": "role.deleted" -} -``` + - `num_model_requests: number` -### Example + The count of requests made to the model. -```http -curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `object: "organization.usage.images.result"` -#### Response + - `"organization.usage.images.result"` -```json -{ - "object": "role.deleted", - "id": "role_01J1F8PROJ", - "deleted": true -} -``` + - `api_key_id: optional string` -## Domain Types + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Role Delete Response + - `model: optional string` -- `RoleDeleteResponse object { id, deleted, object }` + When `group_by=model`, this field provides the model name of the grouped usage result. - Confirmation payload returned after deleting a role. + - `project_id: optional string` - - `id: string` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - Identifier of the deleted role. + - `size: optional string` - - `deleted: boolean` + When `group_by=size`, this field provides the image size of the grouped usage result. - Whether the role was deleted. + - `source: optional string` - - `object: "role.deleted"` + When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. - Always `role.deleted`. + - `user_id: optional string` - - `"role.deleted"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -# Data Retention + - `OrganizationUsageAudioSpeechesResult object { characters, num_model_requests, object, 4 more }` -## Retrieve project data retention + The aggregated audio speeches usage details of the specific time bucket. -**get** `/organization/projects/{project_id}/data_retention` + - `characters: number` -Retrieves project data retention controls. + The number of characters processed. -### Path Parameters + - `num_model_requests: number` -- `project_id: string` + The count of requests made to the model. -### Returns + - `object: "organization.usage.audio_speeches.result"` -- `ProjectDataRetention object { object, type }` + - `"organization.usage.audio_speeches.result"` - Represents a project's data retention control setting. + - `api_key_id: optional string` - - `object: "project.data_retention"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The object type, which is always `project.data_retention`. + - `model: optional string` - - `"project.data_retention"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` + - `project_id: optional string` - The configured project data retention type. + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"organization_default"` + - `user_id: optional string` - - `"none"` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. - - `"zero_data_retention"` + - `OrganizationUsageAudioTranscriptionsResult object { num_model_requests, object, seconds, 4 more }` - - `"modified_abuse_monitoring"` + The aggregated audio transcriptions usage details of the specific time bucket. - - `"enhanced_zero_data_retention"` + - `num_model_requests: number` - - `"enhanced_modified_abuse_monitoring"` + The count of requests made to the model. -### Example + - `object: "organization.usage.audio_transcriptions.result"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.usage.audio_transcriptions.result"` -#### Response + - `seconds: number` -```json -{ - "object": "project.data_retention", - "type": "organization_default" -} -``` + The number of seconds processed. -### Example + - `api_key_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -#### Response + - `model: optional string` -```json -{ - "object": "project.data_retention", - "type": "organization_default" -} -``` + When `group_by=model`, this field provides the model name of the grouped usage result. -## Update project data retention + - `project_id: optional string` -**post** `/organization/projects/{project_id}/data_retention` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -Updates project data retention controls. + - `user_id: optional string` -### Path Parameters + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -- `project_id: string` + - `OrganizationUsageVectorStoresResult object { object, usage_bytes, project_id }` -### Body Parameters + The aggregated vector stores usage details of the specific time bucket. -- `retention_type: "organization_default" or "none" or "zero_data_retention" or 3 more` + - `object: "organization.usage.vector_stores.result"` - The desired project data retention type. + - `"organization.usage.vector_stores.result"` - - `"organization_default"` + - `usage_bytes: number` - - `"none"` + The vector stores usage in bytes. - - `"zero_data_retention"` + - `project_id: optional string` - - `"modified_abuse_monitoring"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"enhanced_zero_data_retention"` + - `OrganizationUsageCodeInterpreterSessionsResult object { num_sessions, object, project_id }` - - `"enhanced_modified_abuse_monitoring"` + The aggregated code interpreter sessions usage details of the specific time bucket. -### Returns + - `num_sessions: number` -- `ProjectDataRetention object { object, type }` + The number of code interpreter sessions. - Represents a project's data retention control setting. + - `object: "organization.usage.code_interpreter_sessions.result"` - - `object: "project.data_retention"` + - `"organization.usage.code_interpreter_sessions.result"` - The object type, which is always `project.data_retention`. + - `project_id: optional string` - - `"project.data_retention"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` + - `OrganizationUsageFileSearchesResult object { num_requests, object, api_key_id, 3 more }` - The configured project data retention type. + The aggregated file search calls usage details of the specific time bucket. - - `"organization_default"` + - `num_requests: number` - - `"none"` + The count of file search calls. - - `"zero_data_retention"` + - `object: "organization.usage.file_searches.result"` - - `"modified_abuse_monitoring"` + - `"organization.usage.file_searches.result"` - - `"enhanced_zero_data_retention"` + - `api_key_id: optional string` - - `"enhanced_modified_abuse_monitoring"` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. -### Example + - `project_id: optional string` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/data_retention \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "retention_type": "organization_default" - }' -``` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. -#### Response + - `user_id: optional string` -```json -{ - "object": "project.data_retention", - "type": "organization_default" -} -``` + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -### Example + - `vector_store_id: optional string` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/data_retention \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "retention_type": "modified_abuse_monitoring" - }' -``` + When `group_by=vector_store_id`, this field provides the vector store ID of the grouped usage result. -#### Response + - `OrganizationUsageWebSearchesResult object { num_model_requests, num_requests, object, 5 more }` -```json -{ - "object": "project.data_retention", - "type": "modified_abuse_monitoring" -} -``` + The aggregated web search calls usage details of the specific time bucket. -## Domain Types + - `num_model_requests: number` -### Project Data Retention + The count of model requests. -- `ProjectDataRetention object { object, type }` + - `num_requests: number` - Represents a project's data retention control setting. + The count of web search calls. - - `object: "project.data_retention"` + - `object: "organization.usage.web_searches.result"` - The object type, which is always `project.data_retention`. + - `"organization.usage.web_searches.result"` - - `"project.data_retention"` + - `api_key_id: optional string` - - `type: "organization_default" or "none" or "zero_data_retention" or 3 more` + When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. - The configured project data retention type. + - `context_level: optional string` - - `"organization_default"` + When `group_by=context_level`, this field provides the search context size of the grouped usage result. - - `"none"` + - `model: optional string` - - `"zero_data_retention"` + When `group_by=model`, this field provides the model name of the grouped usage result. - - `"modified_abuse_monitoring"` + - `project_id: optional string` - - `"enhanced_zero_data_retention"` + When `group_by=project_id`, this field provides the project ID of the grouped usage result. - - `"enhanced_modified_abuse_monitoring"` + - `user_id: optional string` -# Spend Limit + When `group_by=user_id`, this field provides the user ID of the grouped usage result. -## Retrieve project spend limit + - `OrganizationCostsResult object { object, amount, api_key_id, 3 more }` -**get** `/organization/projects/{project_id}/spend_limit` + The aggregated costs details of the specific time bucket. -Get a project's hard spend limit. + - `object: "organization.costs.result"` -### Path Parameters + - `"organization.costs.result"` -- `project_id: string` + - `amount: optional object { currency, value }` -### Returns + The monetary value in its associated currency. -- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` + - `currency: optional string` - Represents a hard spend limit configured at the project level. + Lowercase ISO-4217 currency e.g. "usd" - - `currency: string or "USD"` + - `value: optional number` - The currency for the threshold amount. Currently, only `USD` is supported. + The numeric value of the cost. - - `string` + - `api_key_id: optional string` - - `"USD"` + When `group_by=api_key_id`, this field provides the API Key ID of the grouped costs result. - The currency for the threshold amount. Currently, only `USD` is supported. + - `line_item: optional string` - - `"USD"` + When `group_by=line_item`, this field provides the line item of the grouped costs result. - - `enforcement: object { status }` + - `project_id: optional string` - The current enforcement state of the hard spend limit. + When `group_by=project_id`, this field provides the project ID of the grouped costs result. - - `status: string or "inactive" or "enforcing"` + - `quantity: optional number` - Whether the hard spend limit is currently enforcing. + When `group_by=line_item`, this field provides the quantity of the grouped costs result. - - `string` + - `start_time: number` - - `"inactive" or "enforcing"` + - `has_more: boolean` - Whether the hard spend limit is currently enforcing. + - `next_page: string` - - `"inactive"` + - `object: "page"` - - `"enforcing"` + - `"page"` - - `interval: string or "month"` +# Users - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +## Delete user - - `string` +**delete** `/organization/users/{user_id}` - - `"month"` +Deletes a user from the organization. - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +### Path Parameters - - `"month"` +- `user_id: string` - - `object: "project.spend_limit"` +### Returns - The object type, which is always `project.spend_limit`. +- `id: string` - - `"project.spend_limit"` +- `deleted: boolean` - - `threshold_amount: number` +- `object: "organization.user.deleted"` - The hard spend limit amount, in cents. + - `"organization.user.deleted"` ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ +curl https://api.openai.com/v1/organization/users/$USER_ID \ + -X DELETE \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -27738,20 +27651,16 @@ curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ ```json { - "currency": "USD", - "enforcement": { - "status": "inactive" - }, - "interval": "month", - "object": "project.spend_limit", - "threshold_amount": 0 + "id": "id", + "deleted": true, + "object": "organization.user.deleted" } ``` ### Example ```http -curl https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ +curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ``` @@ -27760,857 +27669,896 @@ curl https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ ```json { - "object": "project.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" - } + "object": "organization.user.deleted", + "id": "user_abc", + "deleted": true } ``` -## Update project spend limit +## List users -**post** `/organization/projects/{project_id}/spend_limit` +**get** `/organization/users` -Create or replace a project's hard spend limit. +Lists all of the users in the organization. -### Path Parameters +### Query Parameters -- `project_id: string` +- `after: optional string` -### Body Parameters + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. -- `currency: "USD"` +- `emails: optional array of string` - The currency for the threshold amount. Currently, only `USD` is supported. + Filter by the email address of users. - - `"USD"` +- `limit: optional number` -- `interval: "month"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + +### Returns + +- `data: array of OrganizationUser` + + - `id: string` + + The identifier, which can be referenced in API endpoints + + - `added_at: number` + + The Unix timestamp (in seconds) of when the user was added. + + - `object: "organization.user"` + + The object type, which is always `organization.user` + + - `"organization.user"` + + - `api_key_last_used_at: optional number` + + The Unix timestamp (in seconds) of the user's last API key usage. + + - `created: optional number` + + The Unix timestamp (in seconds) of when the user was created. + + - `developer_persona: optional string` + + The developer persona metadata for the user. + + - `email: optional string` + + The email address of the user + + - `is_default: optional boolean` + + Whether this is the organization's default user. + + - `is_scale_tier_authorized_purchaser: optional boolean` + + Whether the user is an authorized purchaser for Scale Tier. + + - `is_scim_managed: optional boolean` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + Whether the user is managed through SCIM. - - `"month"` + - `is_service_account: optional boolean` -- `threshold_amount: number` + Whether the user is a service account. - The hard spend limit amount, in cents. + - `name: optional string` -### Returns + The name of the user -- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` + - `projects: optional object { data, object }` - Represents a hard spend limit configured at the project level. + Projects associated with the user, if included. - - `currency: string or "USD"` + - `data: array of object { id, name, role }` - The currency for the threshold amount. Currently, only `USD` is supported. + - `id: optional string` - - `string` + - `name: optional string` - - `"USD"` + - `role: optional string` - The currency for the threshold amount. Currently, only `USD` is supported. + - `object: "list"` - - `"USD"` + - `"list"` - - `enforcement: object { status }` + - `role: optional string` - The current enforcement state of the hard spend limit. + `owner` or `reader` - - `status: string or "inactive" or "enforcing"` + - `technical_level: optional string` - Whether the hard spend limit is currently enforcing. + The technical level metadata for the user. - - `string` + - `user: optional object { id, object, banned, 5 more }` - - `"inactive" or "enforcing"` + Nested user details. - Whether the hard spend limit is currently enforcing. + - `id: string` - - `"inactive"` + - `object: "user"` - - `"enforcing"` + - `"user"` - - `interval: string or "month"` + - `banned: optional boolean` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + - `banned_at: optional number` - - `string` + - `email: optional string` - - `"month"` + - `enabled: optional boolean` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. + - `name: optional string` - - `"month"` + - `picture: optional string` - - `object: "project.spend_limit"` +- `has_more: boolean` - The object type, which is always `project.spend_limit`. +- `object: "list"` - - `"project.spend_limit"` + - `"list"` - - `threshold_amount: number` +- `first_id: optional string` - The hard spend limit amount, in cents. +- `last_id: optional string` ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "currency": "USD", - "interval": "month", - "threshold_amount": 1 - }' +curl https://api.openai.com/v1/organization/users \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` #### Response ```json { - "currency": "USD", - "enforcement": { - "status": "inactive" + "data": [ + { + "id": "id", + "added_at": 0, + "object": "organization.user", + "api_key_last_used_at": 0, + "created": 0, + "developer_persona": "developer_persona", + "email": "email", + "is_default": true, + "is_scale_tier_authorized_purchaser": true, + "is_scim_managed": true, + "is_service_account": true, + "name": "name", + "projects": { + "data": [ + { + "id": "id", + "name": "name", + "role": "role" + } + ], + "object": "list" }, - "interval": "month", - "object": "project.spend_limit", - "threshold_amount": 0 + "role": "role", + "technical_level": "technical_level", + "user": { + "id": "id", + "object": "user", + "banned": true, + "banned_at": 0, + "email": "email", + "enabled": true, + "name": "name", + "picture": "picture" + } + } + ], + "has_more": true, + "object": "list", + "first_id": "first_id", + "last_id": "last_id" } ``` ### Example ```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ +curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 10000, - "currency": "USD", - "interval": "month" - }' + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "project.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" + "object": "list", + "data": [ + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 } + ], + "first_id": "user-abc", + "last_id": "user-xyz", + "has_more": false } ``` -## Delete project spend limit +## Retrieve user -**delete** `/organization/projects/{project_id}/spend_limit` +**get** `/organization/users/{user_id}` -Delete a project's hard spend limit. +Retrieves a user by their identifier. ### Path Parameters -- `project_id: string` +- `user_id: string` ### Returns -- `ProjectSpendLimitDeleted object { deleted, object }` +- `OrganizationUser object { id, added_at, object, 13 more }` - Confirmation payload returned after deleting a project hard spend limit. + Represents an individual `user` within an organization. - - `deleted: boolean` + - `id: string` - Whether the hard spend limit was deleted. + The identifier, which can be referenced in API endpoints - - `object: "project.spend_limit.deleted"` + - `added_at: number` - The object type, which is always `project.spend_limit.deleted`. + The Unix timestamp (in seconds) of when the user was added. - - `"project.spend_limit.deleted"` + - `object: "organization.user"` -### Example + The object type, which is always `organization.user` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_limit \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `"organization.user"` -#### Response + - `api_key_last_used_at: optional number` -```json -{ - "deleted": true, - "object": "project.spend_limit.deleted" -} -``` + The Unix timestamp (in seconds) of the user's last API key usage. -### Example + - `created: optional number` -```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + The Unix timestamp (in seconds) of when the user was created. -#### Response + - `developer_persona: optional string` -```json -{ - "object": "project.spend_limit.deleted", - "deleted": true -} -``` + The developer persona metadata for the user. -## Domain Types + - `email: optional string` -### Project Spend Limit + The email address of the user -- `ProjectSpendLimit object { currency, enforcement, interval, 2 more }` + - `is_default: optional boolean` - Represents a hard spend limit configured at the project level. + Whether this is the organization's default user. - - `currency: string or "USD"` + - `is_scale_tier_authorized_purchaser: optional boolean` + + Whether the user is an authorized purchaser for Scale Tier. + + - `is_scim_managed: optional boolean` + + Whether the user is managed through SCIM. + + - `is_service_account: optional boolean` + + Whether the user is a service account. + + - `name: optional string` + + The name of the user + + - `projects: optional object { data, object }` + + Projects associated with the user, if included. + + - `data: array of object { id, name, role }` + + - `id: optional string` + + - `name: optional string` + + - `role: optional string` + + - `object: "list"` + + - `"list"` + + - `role: optional string` + + `owner` or `reader` + + - `technical_level: optional string` + + The technical level metadata for the user. - The currency for the threshold amount. Currently, only `USD` is supported. + - `user: optional object { id, object, banned, 5 more }` - - `string` + Nested user details. - - `"USD"` + - `id: string` - The currency for the threshold amount. Currently, only `USD` is supported. + - `object: "user"` - - `"USD"` + - `"user"` - - `enforcement: object { status }` + - `banned: optional boolean` - The current enforcement state of the hard spend limit. + - `banned_at: optional number` - - `status: string or "inactive" or "enforcing"` + - `email: optional string` - Whether the hard spend limit is currently enforcing. + - `enabled: optional boolean` - - `string` + - `name: optional string` - - `"inactive" or "enforcing"` + - `picture: optional string` - Whether the hard spend limit is currently enforcing. +### Example - - `"inactive"` +```http +curl https://api.openai.com/v1/organization/users/$USER_ID \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` - - `"enforcing"` +#### Response - - `interval: string or "month"` +```json +{ + "id": "id", + "added_at": 0, + "object": "organization.user", + "api_key_last_used_at": 0, + "created": 0, + "developer_persona": "developer_persona", + "email": "email", + "is_default": true, + "is_scale_tier_authorized_purchaser": true, + "is_scim_managed": true, + "is_service_account": true, + "name": "name", + "projects": { + "data": [ + { + "id": "id", + "name": "name", + "role": "role" + } + ], + "object": "list" + }, + "role": "role", + "technical_level": "technical_level", + "user": { + "id": "id", + "object": "user", + "banned": true, + "banned_at": 0, + "email": "email", + "enabled": true, + "name": "name", + "picture": "picture" + } +} +``` - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +### Example - - `string` +```http +curl https://api.openai.com/v1/organization/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` - - `"month"` +#### Response - The time interval for evaluating spend against the threshold. Currently, only `month` is supported. +```json +{ + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 +} +``` - - `"month"` +## Modify user - - `object: "project.spend_limit"` +**post** `/organization/users/{user_id}` - The object type, which is always `project.spend_limit`. +Modifies a user's role in the organization. - - `"project.spend_limit"` +### Path Parameters - - `threshold_amount: number` +- `user_id: string` - The hard spend limit amount, in cents. +### Body Parameters -### Project Spend Limit Deleted +- `developer_persona: optional string` -- `ProjectSpendLimitDeleted object { deleted, object }` + Developer persona metadata. - Confirmation payload returned after deleting a project hard spend limit. +- `role: optional string` - - `deleted: boolean` + `owner` or `reader` - Whether the hard spend limit was deleted. +- `role_id: optional string` - - `object: "project.spend_limit.deleted"` + Role ID to assign to the user. - The object type, which is always `project.spend_limit.deleted`. +- `technical_level: optional string` - - `"project.spend_limit.deleted"` + Technical level metadata. -# Spend Alerts +### Returns -## List project spend alerts +- `OrganizationUser object { id, added_at, object, 13 more }` -**get** `/organization/projects/{project_id}/spend_alerts` + Represents an individual `user` within an organization. -Lists project spend alerts. + - `id: string` -### Path Parameters + The identifier, which can be referenced in API endpoints -- `project_id: string` + - `added_at: number` -### Query Parameters + The Unix timestamp (in seconds) of when the user was added. -- `after: optional string` + - `object: "organization.user"` - Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page. + The object type, which is always `organization.user` -- `before: optional string` + - `"organization.user"` - Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page. + - `api_key_last_used_at: optional number` -- `limit: optional number` + The Unix timestamp (in seconds) of the user's last API key usage. - A limit on the number of spend alerts to return. Defaults to 20. + - `created: optional number` -- `order: optional "asc" or "desc"` + The Unix timestamp (in seconds) of when the user was created. - Sort order for the returned spend alerts. + - `developer_persona: optional string` - - `"asc"` + The developer persona metadata for the user. - - `"desc"` + - `email: optional string` -### Returns + The email address of the user -- `data: array of ProjectSpendAlert` + - `is_default: optional boolean` - Spend alerts returned in the current page. + Whether this is the organization's default user. - - `id: string` + - `is_scale_tier_authorized_purchaser: optional boolean` - The identifier, which can be referenced in API endpoints. + Whether the user is an authorized purchaser for Scale Tier. - - `currency: "USD"` + - `is_scim_managed: optional boolean` - The currency for the threshold amount. + Whether the user is managed through SCIM. - - `"USD"` + - `is_service_account: optional boolean` - - `interval: "month"` + Whether the user is a service account. - The time interval for evaluating spend against the threshold. + - `name: optional string` - - `"month"` + The name of the user - - `notification_channel: object { recipients, type, subject_prefix }` + - `projects: optional object { data, object }` - Email notification settings for a spend alert. + Projects associated with the user, if included. - - `recipients: array of string` + - `data: array of object { id, name, role }` - Email addresses that receive the spend alert notification. + - `id: optional string` - - `type: "email"` + - `name: optional string` - The notification channel type. Currently only `email` is supported. + - `role: optional string` - - `"email"` + - `object: "list"` - - `subject_prefix: optional string` + - `"list"` - Optional subject prefix for alert emails. + - `role: optional string` - - `object: "project.spend_alert"` + `owner` or `reader` - The object type, which is always `project.spend_alert`. + - `technical_level: optional string` - - `"project.spend_alert"` + The technical level metadata for the user. - - `threshold_amount: number` + - `user: optional object { id, object, banned, 5 more }` - The alert threshold amount, in cents. + Nested user details. -- `first_id: string` + - `id: string` - The ID of the first spend alert in this page. + - `object: "user"` -- `has_more: boolean` + - `"user"` - Whether more spend alerts are available when paginating. + - `banned: optional boolean` -- `last_id: string` + - `banned_at: optional number` - The ID of the last spend alert in this page. + - `email: optional string` -- `object: "list"` + - `enabled: optional boolean` - Always `list`. + - `name: optional string` - - `"list"` + - `picture: optional string` ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +curl https://api.openai.com/v1/organization/users/$USER_ID \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -d '{}' ``` #### Response ```json { + "id": "id", + "added_at": 0, + "object": "organization.user", + "api_key_last_used_at": 0, + "created": 0, + "developer_persona": "developer_persona", + "email": "email", + "is_default": true, + "is_scale_tier_authorized_purchaser": true, + "is_scim_managed": true, + "is_service_account": true, + "name": "name", + "projects": { "data": [ { "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "project.spend_alert", - "threshold_amount": 0 + "name": "name", + "role": "role" } ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", "object": "list" + }, + "role": "role", + "technical_level": "technical_level", + "user": { + "id": "id", + "object": "user", + "banned": true, + "banned_at": 0, + "email": "email", + "enabled": true, + "name": "name", + "picture": "picture" + } } ``` ### Example ```http -curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts?limit=20&order=asc \ +curl -X POST https://api.openai.com/v1/organization/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "alert_abc123", - "object": "project.spend_alert", - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } - } - ], - "first_id": "alert_abc123", - "last_id": "alert_abc123", - "has_more": false + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 } ``` -## Create project spend alert - -**post** `/organization/projects/{project_id}/spend_alerts` - -Creates a project spend alert. - -### Path Parameters - -- `project_id: string` - -### Body Parameters - -- `currency: "USD"` +## Domain Types - The currency for the threshold amount. +### Organization User - - `"USD"` +- `OrganizationUser object { id, added_at, object, 13 more }` -- `interval: "month"` + Represents an individual `user` within an organization. - The time interval for evaluating spend against the threshold. + - `id: string` - - `"month"` + The identifier, which can be referenced in API endpoints -- `notification_channel: object { recipients, type, subject_prefix }` + - `added_at: number` - Email notification settings for a spend alert. + The Unix timestamp (in seconds) of when the user was added. - - `recipients: array of string` + - `object: "organization.user"` - Email addresses that receive the spend alert notification. + The object type, which is always `organization.user` - - `type: "email"` + - `"organization.user"` - The notification channel type. Currently only `email` is supported. + - `api_key_last_used_at: optional number` - - `"email"` + The Unix timestamp (in seconds) of the user's last API key usage. - - `subject_prefix: optional string` + - `created: optional number` - Optional subject prefix for alert emails. + The Unix timestamp (in seconds) of when the user was created. -- `threshold_amount: number` + - `developer_persona: optional string` - The alert threshold amount, in cents. + The developer persona metadata for the user. -### Returns + - `email: optional string` -- `ProjectSpendAlert object { id, currency, interval, 3 more }` + The email address of the user - Represents a spend alert configured at the project level. + - `is_default: optional boolean` - - `id: string` + Whether this is the organization's default user. - The identifier, which can be referenced in API endpoints. + - `is_scale_tier_authorized_purchaser: optional boolean` - - `currency: "USD"` + Whether the user is an authorized purchaser for Scale Tier. - The currency for the threshold amount. + - `is_scim_managed: optional boolean` - - `"USD"` + Whether the user is managed through SCIM. - - `interval: "month"` + - `is_service_account: optional boolean` - The time interval for evaluating spend against the threshold. + Whether the user is a service account. - - `"month"` + - `name: optional string` - - `notification_channel: object { recipients, type, subject_prefix }` + The name of the user - Email notification settings for a spend alert. + - `projects: optional object { data, object }` - - `recipients: array of string` + Projects associated with the user, if included. - Email addresses that receive the spend alert notification. + - `data: array of object { id, name, role }` - - `type: "email"` + - `id: optional string` - The notification channel type. Currently only `email` is supported. + - `name: optional string` - - `"email"` + - `role: optional string` - - `subject_prefix: optional string` + - `object: "list"` - Optional subject prefix for alert emails. + - `"list"` - - `object: "project.spend_alert"` + - `role: optional string` - The object type, which is always `project.spend_alert`. + `owner` or `reader` - - `"project.spend_alert"` + - `technical_level: optional string` - - `threshold_amount: number` + The technical level metadata for the user. - The alert threshold amount, in cents. + - `user: optional object { id, object, banned, 5 more }` -### Example + Nested user details. -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email" - }, - "threshold_amount": 0 - }' -``` + - `id: string` -#### Response + - `object: "user"` -```json -{ - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "project.spend_alert", - "threshold_amount": 0 -} -``` + - `"user"` -### Example + - `banned: optional boolean` -```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } - }' -``` + - `banned_at: optional number` -#### Response + - `email: optional string` -```json -{ - "id": "alert_abc123", - "object": "project.spend_alert", - "threshold_amount": 100000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } -} -``` + - `enabled: optional boolean` -## Retrieve project spend alert + - `name: optional string` -**get** `/organization/projects/{project_id}/spend_alerts/{alert_id}` + - `picture: optional string` -Retrieves a project spend alert. +### User Delete Response -### Path Parameters +- `UserDeleteResponse object { id, deleted, object }` -- `project_id: string` + - `id: string` -- `alert_id: string` + - `deleted: boolean` -### Returns + - `object: "organization.user.deleted"` -- `ProjectSpendAlert object { id, currency, interval, 3 more }` + - `"organization.user.deleted"` - Represents a spend alert configured at the project level. +# Roles - - `id: string` +## Assign organization role to user - The identifier, which can be referenced in API endpoints. +**post** `/organization/users/{user_id}/roles` - - `currency: "USD"` +Assigns an organization role to a user within the organization. - The currency for the threshold amount. +### Path Parameters - - `"USD"` +- `user_id: string` - - `interval: "month"` +### Body Parameters - The time interval for evaluating spend against the threshold. +- `role_id: string` - - `"month"` + Identifier of the role to assign. - - `notification_channel: object { recipients, type, subject_prefix }` +### Returns - Email notification settings for a spend alert. +- `object: "user.role"` - - `recipients: array of string` + Always `user.role`. - Email addresses that receive the spend alert notification. + - `"user.role"` - - `type: "email"` +- `role: Role` - The notification channel type. Currently only `email` is supported. + Details about a role that can be assigned through the public Roles API. - - `"email"` + - `id: string` - - `subject_prefix: optional string` + Identifier for the role. - Optional subject prefix for alert emails. + - `description: string` - - `object: "project.spend_alert"` + Optional description of the role. - The object type, which is always `project.spend_alert`. + - `name: string` - - `"project.spend_alert"` + Unique name for the role. - - `threshold_amount: number` + - `object: "role"` - The alert threshold amount, in cents. + Always `role`. -### Example + - `"role"` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" -``` + - `permissions: array of string` -#### Response + Permissions granted by the role. -```json -{ - "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email", - "subject_prefix": "subject_prefix" - }, - "object": "project.spend_alert", - "threshold_amount": 0 -} -``` + - `predefined_role: boolean` -### Example + Whether the role is predefined and managed by OpenAI. -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" -``` + - `resource_type: string` -#### Response + Resource type the role is bound to (for example `api.organization` or `api.project`). -```json -{ - "id": "alert_abc123", - "object": "project.spend_alert", - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } -} -``` +- `user: OrganizationUser` -## Update project spend alert + Represents an individual `user` within an organization. -**post** `/organization/projects/{project_id}/spend_alerts/{alert_id}` + - `id: string` -Updates a project spend alert. + The identifier, which can be referenced in API endpoints -### Path Parameters + - `added_at: number` -- `project_id: string` + The Unix timestamp (in seconds) of when the user was added. -- `alert_id: string` + - `object: "organization.user"` -### Body Parameters + The object type, which is always `organization.user` -- `currency: "USD"` + - `"organization.user"` - The currency for the threshold amount. + - `api_key_last_used_at: optional number` - - `"USD"` + The Unix timestamp (in seconds) of the user's last API key usage. -- `interval: "month"` + - `created: optional number` - The time interval for evaluating spend against the threshold. + The Unix timestamp (in seconds) of when the user was created. - - `"month"` + - `developer_persona: optional string` -- `notification_channel: object { recipients, type, subject_prefix }` + The developer persona metadata for the user. - Email notification settings for a spend alert. + - `email: optional string` - - `recipients: array of string` + The email address of the user - Email addresses that receive the spend alert notification. + - `is_default: optional boolean` - - `type: "email"` + Whether this is the organization's default user. - The notification channel type. Currently only `email` is supported. + - `is_scale_tier_authorized_purchaser: optional boolean` - - `"email"` + Whether the user is an authorized purchaser for Scale Tier. - - `subject_prefix: optional string` + - `is_scim_managed: optional boolean` - Optional subject prefix for alert emails. + Whether the user is managed through SCIM. -- `threshold_amount: number` + - `is_service_account: optional boolean` - The alert threshold amount, in cents. + Whether the user is a service account. -### Returns + - `name: optional string` -- `ProjectSpendAlert object { id, currency, interval, 3 more }` + The name of the user - Represents a spend alert configured at the project level. + - `projects: optional object { data, object }` - - `id: string` + Projects associated with the user, if included. - The identifier, which can be referenced in API endpoints. + - `data: array of object { id, name, role }` - - `currency: "USD"` + - `id: optional string` - The currency for the threshold amount. + - `name: optional string` - - `"USD"` + - `role: optional string` - - `interval: "month"` + - `object: "list"` - The time interval for evaluating spend against the threshold. + - `"list"` - - `"month"` + - `role: optional string` - - `notification_channel: object { recipients, type, subject_prefix }` + `owner` or `reader` - Email notification settings for a spend alert. + - `technical_level: optional string` - - `recipients: array of string` + The technical level metadata for the user. - Email addresses that receive the spend alert notification. + - `user: optional object { id, object, banned, 5 more }` - - `type: "email"` + Nested user details. - The notification channel type. Currently only `email` is supported. + - `id: string` - - `"email"` + - `object: "user"` - - `subject_prefix: optional string` + - `"user"` - Optional subject prefix for alert emails. + - `banned: optional boolean` - - `object: "project.spend_alert"` + - `banned_at: optional number` - The object type, which is always `project.spend_alert`. + - `email: optional string` - - `"project.spend_alert"` + - `enabled: optional boolean` - - `threshold_amount: number` + - `name: optional string` - The alert threshold amount, in cents. + - `picture: optional string` ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ +curl https://api.openai.com/v1/organization/users/$USER_ID/roles \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -d '{ - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ - "string" - ], - "type": "email" - }, - "threshold_amount": 0 + "role_id": "role_id" }' ``` @@ -28618,36 +28566,65 @@ curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$A ```json { + "object": "user.role", + "role": { "id": "id", - "currency": "USD", - "interval": "month", - "notification_channel": { - "recipients": [ + "description": "description", + "name": "name", + "object": "role", + "permissions": [ "string" ], - "type": "email", - "subject_prefix": "subject_prefix" + "predefined_role": true, + "resource_type": "resource_type" }, - "object": "project.spend_alert", - "threshold_amount": 0 + "user": { + "id": "id", + "added_at": 0, + "object": "organization.user", + "api_key_last_used_at": 0, + "created": 0, + "developer_persona": "developer_persona", + "email": "email", + "is_default": true, + "is_scale_tier_authorized_purchaser": true, + "is_scim_managed": true, + "is_service_account": true, + "name": "name", + "projects": { + "data": [ + { + "id": "id", + "name": "name", + "role": "role" + } + ], + "object": "list" + }, + "role": "role", + "technical_level": "technical_level", + "user": { + "id": "id", + "object": "user", + "banned": true, + "banned_at": 0, + "email": "email", + "enabled": true, + "name": "name", + "picture": "picture" + } + } } ``` ### Example ```http -curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ +curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" - } + "role_id": "role_01J1F8ROLE01" }' ``` @@ -28655,55 +28632,56 @@ curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_aler ```json { - "id": "alert_abc123", - "object": "project.spend_alert", - "threshold_amount": 150000, - "currency": "USD", - "interval": "month", - "notification_channel": { - "type": "email", - "recipients": ["finance@example.com"], - "subject_prefix": "OpenAI spend alert" + "object": "user.role", + "user": { + "object": "organization.user", + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com", + "role": "owner", + "added_at": 1711470000 + }, + "role": { + "object": "role", + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "description": "Allows managing organization groups", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false } } ``` -## Delete project spend alert +## Unassign organization role from user -**delete** `/organization/projects/{project_id}/spend_alerts/{alert_id}` +**delete** `/organization/users/{user_id}/roles/{role_id}` -Deletes a project spend alert. +Unassigns an organization role from a user within the organization. ### Path Parameters -- `project_id: string` +- `user_id: string` -- `alert_id: string` +- `role_id: string` ### Returns -- `ProjectSpendAlertDeleted object { id, deleted, object }` - - Confirmation payload returned after deleting a project spend alert. - - - `id: string` - - The deleted spend alert ID. - - - `deleted: boolean` - - Whether the spend alert was deleted. +- `deleted: boolean` - - `object: "project.spend_alert.deleted"` + Whether the assignment was removed. - Always `project.spend_alert.deleted`. +- `object: string` - - `"project.spend_alert.deleted"` + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$ALERT_ID \ +curl https://api.openai.com/v1/organization/users/$USER_ID/roles/$ROLE_ID \ -X DELETE \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -28712,16 +28690,15 @@ curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/spend_alerts/$A ```json { - "id": "id", "deleted": true, - "object": "project.spend_alert.deleted" + "object": "object" } ``` ### Example ```http -curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \ +curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ``` @@ -28730,164 +28707,265 @@ curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_al ```json { - "id": "alert_abc123", - "object": "project.spend_alert.deleted", + "object": "user.role.deleted", "deleted": true } ``` -## Domain Types +## List user organization role assignments -### Project Spend Alert +**get** `/organization/users/{user_id}/roles` -- `ProjectSpendAlert object { id, currency, interval, 3 more }` +Lists the organization roles assigned to a user within the organization. - Represents a spend alert configured at the project level. +### Path Parameters + +- `user_id: string` + +### Query Parameters + +- `after: optional string` + + Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles. + +- `limit: optional number` + + A limit on the number of organization role assignments to return. + +- `order: optional "asc" or "desc"` + + Sort order for the returned organization roles. + + - `"asc"` + + - `"desc"` + +### Returns + +- `data: array of object { id, assignment_sources, created_at, 9 more }` + + Role assignments returned in the current page. - `id: string` - The identifier, which can be referenced in API endpoints. + Identifier for the role. - - `currency: "USD"` + - `assignment_sources: array of object { principal_id, principal_type }` - The currency for the threshold amount. + Principals from which the role assignment is inherited, when available. - - `"USD"` + - `principal_id: string` - - `interval: "month"` + - `principal_type: string` - The time interval for evaluating spend against the threshold. + - `created_at: number` - - `"month"` + When the role was created. - - `notification_channel: object { recipients, type, subject_prefix }` + - `created_by: string` - Email notification settings for a spend alert. + Identifier of the actor who created the role. - - `recipients: array of string` + - `created_by_user_obj: map[unknown]` - Email addresses that receive the spend alert notification. + User details for the actor that created the role, when available. - - `type: "email"` + - `description: string` - The notification channel type. Currently only `email` is supported. + Description of the role. - - `"email"` + - `metadata: map[unknown]` - - `subject_prefix: optional string` + Arbitrary metadata stored on the role. - Optional subject prefix for alert emails. + - `name: string` - - `object: "project.spend_alert"` + Name of the role. - The object type, which is always `project.spend_alert`. + - `permissions: array of string` - - `"project.spend_alert"` + Permissions associated with the role. - - `threshold_amount: number` + - `predefined_role: boolean` - The alert threshold amount, in cents. + Whether the role is predefined by OpenAI. -### Project Spend Alert Deleted + - `resource_type: string` -- `ProjectSpendAlertDeleted object { id, deleted, object }` + Resource type the role applies to. - Confirmation payload returned after deleting a project spend alert. + - `updated_at: number` - - `id: string` + When the role was last updated. - The deleted spend alert ID. +- `has_more: boolean` - - `deleted: boolean` + Whether additional assignments are available when paginating. - Whether the spend alert was deleted. +- `next: string` - - `object: "project.spend_alert.deleted"` + Cursor to fetch the next page of results, or `null` when there are no more assignments. - Always `project.spend_alert.deleted`. +- `object: "list"` - - `"project.spend_alert.deleted"` + Always `list`. -# Certificates + - `"list"` -## List project certificates +### Example -**get** `/organization/projects/{project_id}/certificates` +```http +curl https://api.openai.com/v1/organization/users/$USER_ID/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" +``` -List certificates for this project. +#### Response -### Path Parameters +```json +{ + "data": [ + { + "id": "id", + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], + "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, + "name": "name", + "permissions": [ + "string" + ], + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 + } + ], + "has_more": true, + "next": "next", + "object": "list" +} +``` -- `project_id: string` +### Example -### Query Parameters +```http +curl https://api.openai.com/v1/organization/users/user_abc123/roles \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" +``` -- `after: optional string` +#### Response - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. +```json +{ + "object": "list", + "data": [ + { + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" + ], + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": { + "id": "user_abc123", + "name": "Ada Lovelace", + "email": "ada@example.com" + }, + "metadata": {} + } + ], + "has_more": false, + "next": null +} +``` -- `limit: optional number` +## Retrieve user organization role - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. +**get** `/organization/users/{user_id}/roles/{role_id}` -- `order: optional "asc" or "desc"` +Retrieves an organization role assigned to a user. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. +### Path Parameters - - `"asc"` +- `user_id: string` - - `"desc"` +- `role_id: string` ### Returns -- `data: array of object { id, active, certificate_details, 3 more }` +- `id: string` + + Identifier for the role. + +- `assignment_sources: array of object { principal_id, principal_type }` + + Principals from which the role assignment is inherited, when available. + + - `principal_id: string` - - `id: string` + - `principal_type: string` - The identifier, which can be referenced in API endpoints +- `created_at: number` - - `active: boolean` + When the role was created. - Whether the certificate is currently active at the project level. +- `created_by: string` - - `certificate_details: object { expires_at, valid_at }` + Identifier of the actor who created the role. - - `expires_at: optional number` +- `created_by_user_obj: map[unknown]` - The Unix timestamp (in seconds) of when the certificate expires. + User details for the actor that created the role, when available. - - `valid_at: optional number` +- `description: string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + Description of the role. - - `created_at: number` +- `metadata: map[unknown]` - The Unix timestamp (in seconds) of when the certificate was uploaded. + Arbitrary metadata stored on the role. - - `name: string` +- `name: string` - The name of the certificate. + Name of the role. - - `object: "organization.project.certificate"` +- `permissions: array of string` - The object type, which is always `organization.project.certificate`. + Permissions associated with the role. - - `"organization.project.certificate"` +- `predefined_role: boolean` -- `first_id: string` + Whether the role is predefined by OpenAI. -- `has_more: boolean` +- `resource_type: string` -- `last_id: string` + Resource type the role applies to. -- `object: "list"` +- `updated_at: number` - - `"list"` + When the role was last updated. ### Example ```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates \ +curl https://api.openai.com/v1/organization/users/$USER_ID/roles/$ROLE_ID \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ``` @@ -28895,438 +28973,336 @@ curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates \ ```json { - "data": [ - { "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, + "assignment_sources": [ + { + "principal_id": "principal_id", + "principal_type": "principal_type" + } + ], "created_at": 0, + "created_by": "created_by", + "created_by_user_obj": { + "foo": "bar" + }, + "description": "description", + "metadata": { + "foo": "bar" + }, "name": "name", - "object": "organization.project.certificate" - } + "permissions": [ + "string" ], - "first_id": "cert_abc", - "has_more": true, - "last_id": "cert_abc", - "object": "list" + "predefined_role": true, + "resource_type": "resource_type", + "updated_at": 0 } ``` ### Example ```http -curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" +curl https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" ``` #### Response ```json { - "object": "list", - "data": [ - { - "object": "organization.project.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, + "id": "role_01J1F8ROLE01", + "name": "API Group Manager", + "permissions": [ + "api.groups.read", + "api.groups.write" ], - "first_id": "cert_abc", - "last_id": "cert_abc", - "has_more": false + "resource_type": "api.organization", + "predefined_role": false, + "description": "Allows managing organization groups", + "created_at": 1711471533, + "updated_at": 1711472599, + "created_by": "user_abc123", + "created_by_user_obj": null, + "metadata": {}, + "assignment_sources": null } ``` -## Activate certificates for project - -**post** `/organization/projects/{project_id}/certificates/activate` +## Domain Types -Activate certificates at the project level. +### Role Create Response -You can atomically and idempotently activate up to 10 certificates at a time. +- `RoleCreateResponse object { object, role, user }` -### Path Parameters + Role assignment linking a user to a role. -- `project_id: string` + - `object: "user.role"` -### Body Parameters + Always `user.role`. -- `certificate_ids: array of string` + - `"user.role"` -### Returns + - `role: Role` -- `data: array of object { id, active, certificate_details, 3 more }` + Details about a role that can be assigned through the public Roles API. - `id: string` - The identifier, which can be referenced in API endpoints + Identifier for the role. - - `active: boolean` + - `description: string` - Whether the certificate is currently active at the project level. + Optional description of the role. - - `certificate_details: object { expires_at, valid_at }` + - `name: string` - - `expires_at: optional number` + Unique name for the role. - The Unix timestamp (in seconds) of when the certificate expires. + - `object: "role"` - - `valid_at: optional number` + Always `role`. - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `"role"` - - `created_at: number` + - `permissions: array of string` - The Unix timestamp (in seconds) of when the certificate was uploaded. + Permissions granted by the role. - - `name: string` + - `predefined_role: boolean` - The name of the certificate. + Whether the role is predefined and managed by OpenAI. - - `object: "organization.project.certificate"` + - `resource_type: string` - The object type, which is always `organization.project.certificate`. + Resource type the role is bound to (for example `api.organization` or `api.project`). - - `"organization.project.certificate"` + - `user: OrganizationUser` -- `object: "organization.project.certificate.activation"` + Represents an individual `user` within an organization. - The project certificate activation result type. + - `id: string` - - `"organization.project.certificate.activation"` + The identifier, which can be referenced in API endpoints -### Example + - `added_at: number` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates/activate \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "certificate_ids": [ - "cert_abc" - ] - }' -``` + The Unix timestamp (in seconds) of when the user was added. -#### Response + - `object: "organization.user"` -```json -{ - "data": [ - { - "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "organization.project.certificate" - } - ], - "object": "organization.project.certificate.activation" -} -``` + The object type, which is always `organization.user` -### Example + - `"organization.user"` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "certificate_ids": ["cert_abc", "cert_def"] -}' -``` + - `api_key_last_used_at: optional number` -#### Response + The Unix timestamp (in seconds) of the user's last API key usage. -```json -{ - "object": "organization.project.certificate.activation", - "data": [ - { - "object": "organization.project.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - { - "object": "organization.project.certificate", - "id": "cert_def", - "name": "My Example Certificate 2", - "active": true, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - ], -} -``` + - `created: optional number` + + The Unix timestamp (in seconds) of when the user was created. + + - `developer_persona: optional string` + + The developer persona metadata for the user. + + - `email: optional string` + + The email address of the user -## Deactivate certificates for project + - `is_default: optional boolean` -**post** `/organization/projects/{project_id}/certificates/deactivate` + Whether this is the organization's default user. -Deactivate certificates at the project level. You can atomically and -idempotently deactivate up to 10 certificates at a time. + - `is_scale_tier_authorized_purchaser: optional boolean` -### Path Parameters + Whether the user is an authorized purchaser for Scale Tier. -- `project_id: string` + - `is_scim_managed: optional boolean` -### Body Parameters + Whether the user is managed through SCIM. -- `certificate_ids: array of string` + - `is_service_account: optional boolean` -### Returns + Whether the user is a service account. -- `data: array of object { id, active, certificate_details, 3 more }` + - `name: optional string` - - `id: string` + The name of the user - The identifier, which can be referenced in API endpoints + - `projects: optional object { data, object }` - - `active: boolean` + Projects associated with the user, if included. - Whether the certificate is currently active at the project level. + - `data: array of object { id, name, role }` - - `certificate_details: object { expires_at, valid_at }` + - `id: optional string` - - `expires_at: optional number` + - `name: optional string` - The Unix timestamp (in seconds) of when the certificate expires. + - `role: optional string` - - `valid_at: optional number` + - `object: "list"` - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `"list"` - - `created_at: number` + - `role: optional string` - The Unix timestamp (in seconds) of when the certificate was uploaded. + `owner` or `reader` - - `name: string` + - `technical_level: optional string` - The name of the certificate. + The technical level metadata for the user. - - `object: "organization.project.certificate"` + - `user: optional object { id, object, banned, 5 more }` - The object type, which is always `organization.project.certificate`. + Nested user details. - - `"organization.project.certificate"` + - `id: string` -- `object: "organization.project.certificate.deactivation"` + - `object: "user"` - The project certificate deactivation result type. + - `"user"` - - `"organization.project.certificate.deactivation"` + - `banned: optional boolean` -### Example + - `banned_at: optional number` -```http -curl https://api.openai.com/v1/organization/projects/$PROJECT_ID/certificates/deactivate \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -d '{ - "certificate_ids": [ - "cert_abc" - ] - }' -``` + - `email: optional string` -#### Response + - `enabled: optional boolean` -```json -{ - "data": [ - { - "id": "id", - "active": true, - "certificate_details": { - "expires_at": 0, - "valid_at": 0 - }, - "created_at": 0, - "name": "name", - "object": "organization.project.certificate" - } - ], - "object": "organization.project.certificate.deactivation" -} -``` + - `name: optional string` -### Example + - `picture: optional string` -```http -curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \ --H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ --H "Content-Type: application/json" \ --d '{ - "certificate_ids": ["cert_abc", "cert_def"] -}' -``` +### Role Delete Response -#### Response +- `RoleDeleteResponse object { deleted, object }` -```json -{ - "object": "organization.project.certificate.deactivation", - "data": [ - { - "object": "organization.project.certificate", - "id": "cert_abc", - "name": "My Example Certificate", - "active": false, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - { - "object": "organization.project.certificate", - "id": "cert_def", - "name": "My Example Certificate 2", - "active": false, - "created_at": 1234567, - "certificate_details": { - "valid_at": 12345667, - "expires_at": 12345678 - } - }, - ], -} -``` + Confirmation payload returned after unassigning a role. -## Domain Types + - `deleted: boolean` -### Certificate List Response + Whether the assignment was removed. -- `CertificateListResponse object { id, active, certificate_details, 3 more }` + - `object: string` - Represents an individual certificate configured at the project level. + Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`. - - `id: string` +### Role List Response - The identifier, which can be referenced in API endpoints +- `RoleListResponse object { id, assignment_sources, created_at, 9 more }` - - `active: boolean` + Detailed information about a role assignment entry returned when listing assignments. - Whether the certificate is currently active at the project level. + - `id: string` - - `certificate_details: object { expires_at, valid_at }` + Identifier for the role. - - `expires_at: optional number` + - `assignment_sources: array of object { principal_id, principal_type }` - The Unix timestamp (in seconds) of when the certificate expires. + Principals from which the role assignment is inherited, when available. - - `valid_at: optional number` + - `principal_id: string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + - `principal_type: string` - `created_at: number` - The Unix timestamp (in seconds) of when the certificate was uploaded. - - - `name: string` + When the role was created. - The name of the certificate. + - `created_by: string` - - `object: "organization.project.certificate"` + Identifier of the actor who created the role. - The object type, which is always `organization.project.certificate`. + - `created_by_user_obj: map[unknown]` - - `"organization.project.certificate"` + User details for the actor that created the role, when available. -### Certificate Activate Response + - `description: string` -- `CertificateActivateResponse object { id, active, certificate_details, 3 more }` + Description of the role. - Represents an individual certificate configured at the project level. + - `metadata: map[unknown]` - - `id: string` + Arbitrary metadata stored on the role. - The identifier, which can be referenced in API endpoints + - `name: string` - - `active: boolean` + Name of the role. - Whether the certificate is currently active at the project level. + - `permissions: array of string` - - `certificate_details: object { expires_at, valid_at }` + Permissions associated with the role. - - `expires_at: optional number` + - `predefined_role: boolean` - The Unix timestamp (in seconds) of when the certificate expires. + Whether the role is predefined by OpenAI. - - `valid_at: optional number` + - `resource_type: string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + Resource type the role applies to. - - `created_at: number` + - `updated_at: number` - The Unix timestamp (in seconds) of when the certificate was uploaded. + When the role was last updated. - - `name: string` +### Role Retrieve Response - The name of the certificate. +- `RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }` - - `object: "organization.project.certificate"` + Detailed information about a role assignment entry returned when listing assignments. - The object type, which is always `organization.project.certificate`. + - `id: string` - - `"organization.project.certificate"` + Identifier for the role. -### Certificate Deactivate Response + - `assignment_sources: array of object { principal_id, principal_type }` -- `CertificateDeactivateResponse object { id, active, certificate_details, 3 more }` + Principals from which the role assignment is inherited, when available. - Represents an individual certificate configured at the project level. + - `principal_id: string` - - `id: string` + - `principal_type: string` - The identifier, which can be referenced in API endpoints + - `created_at: number` - - `active: boolean` + When the role was created. - Whether the certificate is currently active at the project level. + - `created_by: string` - - `certificate_details: object { expires_at, valid_at }` + Identifier of the actor who created the role. - - `expires_at: optional number` + - `created_by_user_obj: map[unknown]` - The Unix timestamp (in seconds) of when the certificate expires. + User details for the actor that created the role, when available. - - `valid_at: optional number` + - `description: string` - The Unix timestamp (in seconds) of when the certificate becomes valid. + Description of the role. - - `created_at: number` + - `metadata: map[unknown]` - The Unix timestamp (in seconds) of when the certificate was uploaded. + Arbitrary metadata stored on the role. - `name: string` - The name of the certificate. + Name of the role. - - `object: "organization.project.certificate"` + - `permissions: array of string` - The object type, which is always `organization.project.certificate`. + Permissions associated with the role. - - `"organization.project.certificate"` + - `predefined_role: boolean` + + Whether the role is predefined by OpenAI. + + - `resource_type: string` + + Resource type the role applies to. + + - `updated_at: number` + + When the role was last updated.