Reference 2026-05-27 06:42 UTC to 2026-06-02 06:51 UTC

46 46 

47 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.47 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.

48 48 

49- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`49- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

50 50 

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

52 52 

126 126 

127 - `"tunnel.deleted"`127 - `"tunnel.deleted"`

128 128 

129 - `"workload_identity_provider.created"`

130 

131 - `"workload_identity_provider.updated"`

132 

133 - `"workload_identity_provider.deleted"`

134 

135 - `"workload_identity_provider_mapping.created"`

136 

137 - `"workload_identity_provider_mapping.updated"`

138 

139 - `"workload_identity_provider_mapping.deleted"`

140 

129 - `"role.created"`141 - `"role.created"`

130 142 

131 - `"role.updated"`143 - `"role.updated"`

166 178 

167### Returns179### Returns

168 180 

169- `data: array of object { id, effective_at, type, 49 more }`181- `data: array of object { id, effective_at, type, 55 more }`

170 182 

171 - `id: string`183 - `id: string`

172 184 

176 188 

177 The Unix timestamp (in seconds) of the event.189 The Unix timestamp (in seconds) of the event.

178 190 

179 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`191 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

180 192 

181 The event type.193 The event type.

182 194 

256 268 

257 - `"tunnel.deleted"`269 - `"tunnel.deleted"`

258 270 

271 - `"workload_identity_provider.created"`

272 

273 - `"workload_identity_provider.updated"`

274 

275 - `"workload_identity_provider.deleted"`

276 

277 - `"workload_identity_provider_mapping.created"`

278 

279 - `"workload_identity_provider_mapping.updated"`

280 

281 - `"workload_identity_provider_mapping.deleted"`

282 

259 - `"role.created"`283 - `"role.created"`

260 284 

261 - `"role.updated"`285 - `"role.updated"`

1054 1078 

1055 The role of the user. Is either `owner` or `member`.1079 The role of the user. Is either `owner` or `member`.

1056 1080 

1081 - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }`

1082 

1083 The details for events with this `type`.

1084 

1085 - `id: optional string`

1086 

1087 The workload identity provider mapping ID.

1088 

1089 - `data: optional unknown`

1090 

1091 The payload used to create the workload identity provider mapping.

1092 

1093 - `identity_provider_id: optional string`

1094 

1095 The workload identity provider ID.

1096 

1097 - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }`

1098 

1099 The details for events with this `type`.

1100 

1101 - `id: optional string`

1102 

1103 The workload identity provider mapping ID.

1104 

1105 - `identity_provider_id: optional string`

1106 

1107 The workload identity provider ID.

1108 

1109 - `project_id: optional string`

1110 

1111 The project ID.

1112 

1113 - `service_account_id: optional string`

1114 

1115 The mapped service account ID.

1116 

1117 - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }`

1118 

1119 The details for events with this `type`.

1120 

1121 - `id: optional string`

1122 

1123 The workload identity provider mapping ID.

1124 

1125 - `changes_requested: optional unknown`

1126 

1127 The payload used to update the workload identity provider mapping.

1128 

1129 - `identity_provider_id: optional string`

1130 

1131 The workload identity provider ID.

1132 

1133 - `"workload_identity_provider.created": optional object { id, data }`

1134 

1135 The details for events with this `type`.

1136 

1137 - `id: optional string`

1138 

1139 The workload identity provider ID.

1140 

1141 - `data: optional unknown`

1142 

1143 The payload used to create the workload identity provider.

1144 

1145 - `"workload_identity_provider.deleted": optional object { id, name }`

1146 

1147 The details for events with this `type`.

1148 

1149 - `id: optional string`

1150 

1151 The workload identity provider ID.

1152 

1153 - `name: optional string`

1154 

1155 The workload identity provider name.

1156 

1157 - `"workload_identity_provider.updated": optional object { id, changes_requested }`

1158 

1159 The details for events with this `type`.

1160 

1161 - `id: optional string`

1162 

1163 The workload identity provider ID.

1164 

1165 - `changes_requested: optional unknown`

1166 

1167 The payload used to update the workload identity provider.

1168 

1057- `has_more: boolean`1169- `has_more: boolean`

1058 1170 

1059- `object: "list"`1171- `object: "list"`

1366 "changes_requested": {1478 "changes_requested": {

1367 "role": "role"1479 "role": "role"

1368 }1480 }

1481 },

1482 "workload_identity_provider_mapping.created": {

1483 "id": "id",

1484 "data": {},

1485 "identity_provider_id": "identity_provider_id"

1486 },

1487 "workload_identity_provider_mapping.deleted": {

1488 "id": "id",

1489 "identity_provider_id": "identity_provider_id",

1490 "project_id": "project_id",

1491 "service_account_id": "service_account_id"

1492 },

1493 "workload_identity_provider_mapping.updated": {

1494 "id": "id",

1495 "changes_requested": {},

1496 "identity_provider_id": "identity_provider_id"

1497 },

1498 "workload_identity_provider.created": {

1499 "id": "id",

1500 "data": {}

1501 },

1502 "workload_identity_provider.deleted": {

1503 "id": "id",

1504 "name": "name"

1505 },

1506 "workload_identity_provider.updated": {

1507 "id": "id",

1508 "changes_requested": {}

1369 }1509 }

1370 }1510 }

1371 ],1511 ],

1452 1592 

1453### Audit Log List Response1593### Audit Log List Response

1454 1594 

1455- `AuditLogListResponse object { id, effective_at, type, 49 more }`1595- `AuditLogListResponse object { id, effective_at, type, 55 more }`

1456 1596 

1457 A log of a user action or configuration change within this organization.1597 A log of a user action or configuration change within this organization.

1458 1598 

1464 1604 

1465 The Unix timestamp (in seconds) of the event.1605 The Unix timestamp (in seconds) of the event.

1466 1606 

1467 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`1607 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

1468 1608 

1469 The event type.1609 The event type.

1470 1610 

1544 1684 

1545 - `"tunnel.deleted"`1685 - `"tunnel.deleted"`

1546 1686 

1687 - `"workload_identity_provider.created"`

1688 

1689 - `"workload_identity_provider.updated"`

1690 

1691 - `"workload_identity_provider.deleted"`

1692 

1693 - `"workload_identity_provider_mapping.created"`

1694 

1695 - `"workload_identity_provider_mapping.updated"`

1696 

1697 - `"workload_identity_provider_mapping.deleted"`

1698 

1547 - `"role.created"`1699 - `"role.created"`

1548 1700 

1549 - `"role.updated"`1701 - `"role.updated"`

2342 2494 

2343 The role of the user. Is either `owner` or `member`.2495 The role of the user. Is either `owner` or `member`.

2344 2496 

2497 - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }`

2498 

2499 The details for events with this `type`.

2500 

2501 - `id: optional string`

2502 

2503 The workload identity provider mapping ID.

2504 

2505 - `data: optional unknown`

2506 

2507 The payload used to create the workload identity provider mapping.

2508 

2509 - `identity_provider_id: optional string`

2510 

2511 The workload identity provider ID.

2512 

2513 - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }`

2514 

2515 The details for events with this `type`.

2516 

2517 - `id: optional string`

2518 

2519 The workload identity provider mapping ID.

2520 

2521 - `identity_provider_id: optional string`

2522 

2523 The workload identity provider ID.

2524 

2525 - `project_id: optional string`

2526 

2527 The project ID.

2528 

2529 - `service_account_id: optional string`

2530 

2531 The mapped service account ID.

2532 

2533 - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }`

2534 

2535 The details for events with this `type`.

2536 

2537 - `id: optional string`

2538 

2539 The workload identity provider mapping ID.

2540 

2541 - `changes_requested: optional unknown`

2542 

2543 The payload used to update the workload identity provider mapping.

2544 

2545 - `identity_provider_id: optional string`

2546 

2547 The workload identity provider ID.

2548 

2549 - `"workload_identity_provider.created": optional object { id, data }`

2550 

2551 The details for events with this `type`.

2552 

2553 - `id: optional string`

2554 

2555 The workload identity provider ID.

2556 

2557 - `data: optional unknown`

2558 

2559 The payload used to create the workload identity provider.

2560 

2561 - `"workload_identity_provider.deleted": optional object { id, name }`

2562 

2563 The details for events with this `type`.

2564 

2565 - `id: optional string`

2566 

2567 The workload identity provider ID.

2568 

2569 - `name: optional string`

2570 

2571 The workload identity provider name.

2572 

2573 - `"workload_identity_provider.updated": optional object { id, changes_requested }`

2574 

2575 The details for events with this `type`.

2576 

2577 - `id: optional string`

2578 

2579 The workload identity provider ID.

2580 

2581 - `changes_requested: optional unknown`

2582 

2583 The payload used to update the workload identity provider.

2584 

2345# Admin API Keys2585# Admin API Keys

2346 2586 

2347## List all organization and project API keys.2587## List all organization and project API keys.

44 44 

45 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.45 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.

46 46 

47- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`47- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

48 48 

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

50 50 

124 124 

125 - `"tunnel.deleted"`125 - `"tunnel.deleted"`

126 126 

127 - `"workload_identity_provider.created"`

128 

129 - `"workload_identity_provider.updated"`

130 

131 - `"workload_identity_provider.deleted"`

132 

133 - `"workload_identity_provider_mapping.created"`

134 

135 - `"workload_identity_provider_mapping.updated"`

136 

137 - `"workload_identity_provider_mapping.deleted"`

138 

127 - `"role.created"`139 - `"role.created"`

128 140 

129 - `"role.updated"`141 - `"role.updated"`

164 176 

165### Returns177### Returns

166 178 

167- `data: array of object { id, effective_at, type, 49 more }`179- `data: array of object { id, effective_at, type, 55 more }`

168 180 

169 - `id: string`181 - `id: string`

170 182 

174 186 

175 The Unix timestamp (in seconds) of the event.187 The Unix timestamp (in seconds) of the event.

176 188 

177 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`189 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

178 190 

179 The event type.191 The event type.

180 192 

254 266 

255 - `"tunnel.deleted"`267 - `"tunnel.deleted"`

256 268 

269 - `"workload_identity_provider.created"`

270 

271 - `"workload_identity_provider.updated"`

272 

273 - `"workload_identity_provider.deleted"`

274 

275 - `"workload_identity_provider_mapping.created"`

276 

277 - `"workload_identity_provider_mapping.updated"`

278 

279 - `"workload_identity_provider_mapping.deleted"`

280 

257 - `"role.created"`281 - `"role.created"`

258 282 

259 - `"role.updated"`283 - `"role.updated"`

1052 1076 

1053 The role of the user. Is either `owner` or `member`.1077 The role of the user. Is either `owner` or `member`.

1054 1078 

1079 - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }`

1080 

1081 The details for events with this `type`.

1082 

1083 - `id: optional string`

1084 

1085 The workload identity provider mapping ID.

1086 

1087 - `data: optional unknown`

1088 

1089 The payload used to create the workload identity provider mapping.

1090 

1091 - `identity_provider_id: optional string`

1092 

1093 The workload identity provider ID.

1094 

1095 - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }`

1096 

1097 The details for events with this `type`.

1098 

1099 - `id: optional string`

1100 

1101 The workload identity provider mapping ID.

1102 

1103 - `identity_provider_id: optional string`

1104 

1105 The workload identity provider ID.

1106 

1107 - `project_id: optional string`

1108 

1109 The project ID.

1110 

1111 - `service_account_id: optional string`

1112 

1113 The mapped service account ID.

1114 

1115 - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }`

1116 

1117 The details for events with this `type`.

1118 

1119 - `id: optional string`

1120 

1121 The workload identity provider mapping ID.

1122 

1123 - `changes_requested: optional unknown`

1124 

1125 The payload used to update the workload identity provider mapping.

1126 

1127 - `identity_provider_id: optional string`

1128 

1129 The workload identity provider ID.

1130 

1131 - `"workload_identity_provider.created": optional object { id, data }`

1132 

1133 The details for events with this `type`.

1134 

1135 - `id: optional string`

1136 

1137 The workload identity provider ID.

1138 

1139 - `data: optional unknown`

1140 

1141 The payload used to create the workload identity provider.

1142 

1143 - `"workload_identity_provider.deleted": optional object { id, name }`

1144 

1145 The details for events with this `type`.

1146 

1147 - `id: optional string`

1148 

1149 The workload identity provider ID.

1150 

1151 - `name: optional string`

1152 

1153 The workload identity provider name.

1154 

1155 - `"workload_identity_provider.updated": optional object { id, changes_requested }`

1156 

1157 The details for events with this `type`.

1158 

1159 - `id: optional string`

1160 

1161 The workload identity provider ID.

1162 

1163 - `changes_requested: optional unknown`

1164 

1165 The payload used to update the workload identity provider.

1166 

1055- `has_more: boolean`1167- `has_more: boolean`

1056 1168 

1057- `object: "list"`1169- `object: "list"`

1364 "changes_requested": {1476 "changes_requested": {

1365 "role": "role"1477 "role": "role"

1366 }1478 }

1479 },

1480 "workload_identity_provider_mapping.created": {

1481 "id": "id",

1482 "data": {},

1483 "identity_provider_id": "identity_provider_id"

1484 },

1485 "workload_identity_provider_mapping.deleted": {

1486 "id": "id",

1487 "identity_provider_id": "identity_provider_id",

1488 "project_id": "project_id",

1489 "service_account_id": "service_account_id"

1490 },

1491 "workload_identity_provider_mapping.updated": {

1492 "id": "id",

1493 "changes_requested": {},

1494 "identity_provider_id": "identity_provider_id"

1495 },

1496 "workload_identity_provider.created": {

1497 "id": "id",

1498 "data": {}

1499 },

1500 "workload_identity_provider.deleted": {

1501 "id": "id",

1502 "name": "name"

1503 },

1504 "workload_identity_provider.updated": {

1505 "id": "id",

1506 "changes_requested": {}

1367 }1507 }

1368 }1508 }

1369 ],1509 ],

1450 1590 

1451### Audit Log List Response1591### Audit Log List Response

1452 1592 

1453- `AuditLogListResponse object { id, effective_at, type, 49 more }`1593- `AuditLogListResponse object { id, effective_at, type, 55 more }`

1454 1594 

1455 A log of a user action or configuration change within this organization.1595 A log of a user action or configuration change within this organization.

1456 1596 

1462 1602 

1463 The Unix timestamp (in seconds) of the event.1603 The Unix timestamp (in seconds) of the event.

1464 1604 

1465 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`1605 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

1466 1606 

1467 The event type.1607 The event type.

1468 1608 

1542 1682 

1543 - `"tunnel.deleted"`1683 - `"tunnel.deleted"`

1544 1684 

1685 - `"workload_identity_provider.created"`

1686 

1687 - `"workload_identity_provider.updated"`

1688 

1689 - `"workload_identity_provider.deleted"`

1690 

1691 - `"workload_identity_provider_mapping.created"`

1692 

1693 - `"workload_identity_provider_mapping.updated"`

1694 

1695 - `"workload_identity_provider_mapping.deleted"`

1696 

1545 - `"role.created"`1697 - `"role.created"`

1546 1698 

1547 - `"role.updated"`1699 - `"role.updated"`

2339 - `role: optional string`2491 - `role: optional string`

2340 2492 

2341 The role of the user. Is either `owner` or `member`.2493 The role of the user. Is either `owner` or `member`.

2494 

2495 - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }`

2496 

2497 The details for events with this `type`.

2498 

2499 - `id: optional string`

2500 

2501 The workload identity provider mapping ID.

2502 

2503 - `data: optional unknown`

2504 

2505 The payload used to create the workload identity provider mapping.

2506 

2507 - `identity_provider_id: optional string`

2508 

2509 The workload identity provider ID.

2510 

2511 - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }`

2512 

2513 The details for events with this `type`.

2514 

2515 - `id: optional string`

2516 

2517 The workload identity provider mapping ID.

2518 

2519 - `identity_provider_id: optional string`

2520 

2521 The workload identity provider ID.

2522 

2523 - `project_id: optional string`

2524 

2525 The project ID.

2526 

2527 - `service_account_id: optional string`

2528 

2529 The mapped service account ID.

2530 

2531 - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }`

2532 

2533 The details for events with this `type`.

2534 

2535 - `id: optional string`

2536 

2537 The workload identity provider mapping ID.

2538 

2539 - `changes_requested: optional unknown`

2540 

2541 The payload used to update the workload identity provider mapping.

2542 

2543 - `identity_provider_id: optional string`

2544 

2545 The workload identity provider ID.

2546 

2547 - `"workload_identity_provider.created": optional object { id, data }`

2548 

2549 The details for events with this `type`.

2550 

2551 - `id: optional string`

2552 

2553 The workload identity provider ID.

2554 

2555 - `data: optional unknown`

2556 

2557 The payload used to create the workload identity provider.

2558 

2559 - `"workload_identity_provider.deleted": optional object { id, name }`

2560 

2561 The details for events with this `type`.

2562 

2563 - `id: optional string`

2564 

2565 The workload identity provider ID.

2566 

2567 - `name: optional string`

2568 

2569 The workload identity provider name.

2570 

2571 - `"workload_identity_provider.updated": optional object { id, changes_requested }`

2572 

2573 The details for events with this `type`.

2574 

2575 - `id: optional string`

2576 

2577 The workload identity provider ID.

2578 

2579 - `changes_requested: optional unknown`

2580 

2581 The payload used to update the workload identity provider.

42 42 

43 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.43 Return only events whose `effective_at` (Unix seconds) is less than or equal to this value.

44 44 

45- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`45- `event_types: optional array of "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

46 46 

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

48 48 

122 122 

123 - `"tunnel.deleted"`123 - `"tunnel.deleted"`

124 124 

125 - `"workload_identity_provider.created"`

126 

127 - `"workload_identity_provider.updated"`

128 

129 - `"workload_identity_provider.deleted"`

130 

131 - `"workload_identity_provider_mapping.created"`

132 

133 - `"workload_identity_provider_mapping.updated"`

134 

135 - `"workload_identity_provider_mapping.deleted"`

136 

125 - `"role.created"`137 - `"role.created"`

126 138 

127 - `"role.updated"`139 - `"role.updated"`

162 174 

163### Returns175### Returns

164 176 

165- `data: array of object { id, effective_at, type, 49 more }`177- `data: array of object { id, effective_at, type, 55 more }`

166 178 

167 - `id: string`179 - `id: string`

168 180 

172 184 

173 The Unix timestamp (in seconds) of the event.185 The Unix timestamp (in seconds) of the event.

174 186 

175 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 48 more`187 - `type: "api_key.created" or "api_key.updated" or "api_key.deleted" or 54 more`

176 188 

177 The event type.189 The event type.

178 190 

252 264 

253 - `"tunnel.deleted"`265 - `"tunnel.deleted"`

254 266 

267 - `"workload_identity_provider.created"`

268 

269 - `"workload_identity_provider.updated"`

270 

271 - `"workload_identity_provider.deleted"`

272 

273 - `"workload_identity_provider_mapping.created"`

274 

275 - `"workload_identity_provider_mapping.updated"`

276 

277 - `"workload_identity_provider_mapping.deleted"`

278 

255 - `"role.created"`279 - `"role.created"`

256 280 

257 - `"role.updated"`281 - `"role.updated"`

1050 1074 

1051 The role of the user. Is either `owner` or `member`.1075 The role of the user. Is either `owner` or `member`.

1052 1076 

1077 - `"workload_identity_provider_mapping.created": optional object { id, data, identity_provider_id }`

1078 

1079 The details for events with this `type`.

1080 

1081 - `id: optional string`

1082 

1083 The workload identity provider mapping ID.

1084 

1085 - `data: optional unknown`

1086 

1087 The payload used to create the workload identity provider mapping.

1088 

1089 - `identity_provider_id: optional string`

1090 

1091 The workload identity provider ID.

1092 

1093 - `"workload_identity_provider_mapping.deleted": optional object { id, identity_provider_id, project_id, service_account_id }`

1094 

1095 The details for events with this `type`.

1096 

1097 - `id: optional string`

1098 

1099 The workload identity provider mapping ID.

1100 

1101 - `identity_provider_id: optional string`

1102 

1103 The workload identity provider ID.

1104 

1105 - `project_id: optional string`

1106 

1107 The project ID.

1108 

1109 - `service_account_id: optional string`

1110 

1111 The mapped service account ID.

1112 

1113 - `"workload_identity_provider_mapping.updated": optional object { id, changes_requested, identity_provider_id }`

1114 

1115 The details for events with this `type`.

1116 

1117 - `id: optional string`

1118 

1119 The workload identity provider mapping ID.

1120 

1121 - `changes_requested: optional unknown`

1122 

1123 The payload used to update the workload identity provider mapping.

1124 

1125 - `identity_provider_id: optional string`

1126 

1127 The workload identity provider ID.

1128 

1129 - `"workload_identity_provider.created": optional object { id, data }`

1130 

1131 The details for events with this `type`.

1132 

1133 - `id: optional string`

1134 

1135 The workload identity provider ID.

1136 

1137 - `data: optional unknown`

1138 

1139 The payload used to create the workload identity provider.

1140 

1141 - `"workload_identity_provider.deleted": optional object { id, name }`

1142 

1143 The details for events with this `type`.

1144 

1145 - `id: optional string`

1146 

1147 The workload identity provider ID.

1148 

1149 - `name: optional string`

1150 

1151 The workload identity provider name.

1152 

1153 - `"workload_identity_provider.updated": optional object { id, changes_requested }`

1154 

1155 The details for events with this `type`.

1156 

1157 - `id: optional string`

1158 

1159 The workload identity provider ID.

1160 

1161 - `changes_requested: optional unknown`

1162 

1163 The payload used to update the workload identity provider.

1164 

1053- `has_more: boolean`1165- `has_more: boolean`

1054 1166 

1055- `object: "list"`1167- `object: "list"`

1362 "changes_requested": {1474 "changes_requested": {

1363 "role": "role"1475 "role": "role"

1364 }1476 }

1477 },

1478 "workload_identity_provider_mapping.created": {

1479 "id": "id",

1480 "data": {},

1481 "identity_provider_id": "identity_provider_id"

1482 },

1483 "workload_identity_provider_mapping.deleted": {

1484 "id": "id",

1485 "identity_provider_id": "identity_provider_id",

1486 "project_id": "project_id",

1487 "service_account_id": "service_account_id"

1488 },

1489 "workload_identity_provider_mapping.updated": {

1490 "id": "id",

1491 "changes_requested": {},

1492 "identity_provider_id": "identity_provider_id"

1493 },

1494 "workload_identity_provider.created": {

1495 "id": "id",

1496 "data": {}

1497 },

1498 "workload_identity_provider.deleted": {

1499 "id": "id",

1500 "name": "name"

1501 },

1502 "workload_identity_provider.updated": {

1503 "id": "id",

1504 "changes_requested": {}

1365 }1505 }

1366 }1506 }

1367 ],1507 ],

799- `prompt_cache_retention: optional "in_memory" or "24h"`799- `prompt_cache_retention: optional "in_memory" or "24h"`

800 800 

801 The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention).801 The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](/docs/guides/prompt-caching#prompt-cache-retention).

802 For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported.

803 

804 For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy:

805 

806 - Organizations without ZDR enabled default to `24h`.

807 - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified.

802 808 

803 - `"in_memory"`809 - `"in_memory"`

804 810 

6 6 

7### Body Parameters7### Body Parameters

8 8 

9- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 26 more`9- `items: optional array of EasyInputMessage or object { content, role, status, type } or ResponseOutputMessage or 27 more`

10 10 

11 Initial items to include in the conversation context. You may add up to 20 items at a time.11 Initial items to include in the conversation context. You may add up to 20 items at a time.

12 12 

788 788 

789 The unique ID of the web search tool call.789 The unique ID of the web search tool call.

790 790 

791 - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }`791 - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }`

792 792 

793 An object describing the specific action taken in this web search call.793 An object describing the specific action taken in this web search call.

794 Includes details on how the model used the web (search, open_page, find_in_page).794 Includes details on how the model used the web (search, open_page, find_in_page).

795 795 

796 - `Search object { query, type, queries, sources }`796 - `Search object { type, queries, query, sources }`

797 797 

798 Action type "search" - Performs a web search query.798 Action type "search" - Performs a web search query.

799 799 

800 - `query: string`

801 

802 [DEPRECATED] The search query.

803 

804 - `type: "search"`800 - `type: "search"`

805 801 

806 The action type.802 The action type.

811 807 

812 The search queries.808 The search queries.

813 809 

810 - `query: optional string`

811 

812 The search query.

813 

814 - `sources: optional array of object { type, url }`814 - `sources: optional array of object { type, url }`

815 815 

816 The sources used in the search.816 The sources used in the search.

2082 2082 

2083 - `"incomplete"`2083 - `"incomplete"`

2084 2084 

2085 - `AdditionalTools object { role, tools, type, id }`

2086 

2087 - `role: "developer"`

2088 

2089 The role that provided the additional tools. Only `developer` is supported.

2090 

2091 - `"developer"`

2092 

2093 - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more`

2094 

2095 A list of additional tools made available at this item.

2096 

2097 - `Function object { name, parameters, strict, 3 more }`

2098 

2099 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

2100 

2101 - `name: string`

2102 

2103 The name of the function to call.

2104 

2105 - `parameters: map[unknown]`

2106 

2107 A JSON schema object describing the parameters of the function.

2108 

2109 - `strict: boolean`

2110 

2111 Whether to enforce strict parameter validation. Default `true`.

2112 

2113 - `type: "function"`

2114 

2115 The type of the function tool. Always `function`.

2116 

2117 - `"function"`

2118 

2119 - `defer_loading: optional boolean`

2120 

2121 Whether this function is deferred and loaded via tool search.

2122 

2123 - `description: optional string`

2124 

2125 A description of the function. Used by the model to determine whether or not to call the function.

2126 

2127 - `FileSearch object { type, vector_store_ids, filters, 2 more }`

2128 

2129 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

2130 

2131 - `type: "file_search"`

2132 

2133 The type of the file search tool. Always `file_search`.

2134 

2135 - `"file_search"`

2136 

2137 - `vector_store_ids: array of string`

2138 

2139 The IDs of the vector stores to search.

2140 

2141 - `filters: optional ComparisonFilter or CompoundFilter`

2142 

2143 A filter to apply.

2144 

2145 - `ComparisonFilter object { key, type, value }`

2146 

2147 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

2148 

2149 - `CompoundFilter object { filters, type }`

2150 

2151 Combine multiple filters using `and` or `or`.

2152 

2153 - `max_num_results: optional number`

2154 

2155 The maximum number of results to return. This number should be between 1 and 50 inclusive.

2156 

2157 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }`

2158 

2159 Ranking options for search.

2160 

2161 - `hybrid_search: optional object { embedding_weight, text_weight }`

2162 

2163 Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

2164 

2165 - `embedding_weight: number`

2166 

2167 The weight of the embedding in the reciprocal ranking fusion.

2168 

2169 - `text_weight: number`

2170 

2171 The weight of the text in the reciprocal ranking fusion.

2172 

2173 - `ranker: optional "auto" or "default-2024-11-15"`

2174 

2175 The ranker to use for the file search.

2176 

2177 - `"auto"`

2178 

2179 - `"default-2024-11-15"`

2180 

2181 - `score_threshold: optional number`

2182 

2183 The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

2184 

2185 - `Computer object { type }`

2186 

2187 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2188 

2189 - `type: "computer"`

2190 

2191 The type of the computer tool. Always `computer`.

2192 

2193 - `"computer"`

2194 

2195 - `ComputerUsePreview object { display_height, display_width, environment, type }`

2196 

2197 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2198 

2199 - `display_height: number`

2200 

2201 The height of the computer display.

2202 

2203 - `display_width: number`

2204 

2205 The width of the computer display.

2206 

2207 - `environment: "windows" or "mac" or "linux" or 2 more`

2208 

2209 The type of computer environment to control.

2210 

2211 - `"windows"`

2212 

2213 - `"mac"`

2214 

2215 - `"linux"`

2216 

2217 - `"ubuntu"`

2218 

2219 - `"browser"`

2220 

2221 - `type: "computer_use_preview"`

2222 

2223 The type of the computer use tool. Always `computer_use_preview`.

2224 

2225 - `"computer_use_preview"`

2226 

2227 - `WebSearch object { type, filters, search_context_size, user_location }`

2228 

2229 Search the Internet for sources related to the prompt. Learn more about the

2230 [web search tool](/docs/guides/tools-web-search).

2231 

2232 - `type: "web_search" or "web_search_2025_08_26"`

2233 

2234 The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.

2235 

2236 - `"web_search"`

2237 

2238 - `"web_search_2025_08_26"`

2239 

2240 - `filters: optional object { allowed_domains }`

2241 

2242 Filters for the search.

2243 

2244 - `allowed_domains: optional array of string`

2245 

2246 Allowed domains for the search. If not provided, all domains are allowed.

2247 Subdomains of the provided domains are allowed as well.

2248 

2249 Example: `["pubmed.ncbi.nlm.nih.gov"]`

2250 

2251 - `search_context_size: optional "low" or "medium" or "high"`

2252 

2253 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

2254 

2255 - `"low"`

2256 

2257 - `"medium"`

2258 

2259 - `"high"`

2260 

2261 - `user_location: optional object { city, country, region, 2 more }`

2262 

2263 The approximate location of the user.

2264 

2265 - `city: optional string`

2266 

2267 Free text input for the city of the user, e.g. `San Francisco`.

2268 

2269 - `country: optional string`

2270 

2271 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

2272 

2273 - `region: optional string`

2274 

2275 Free text input for the region of the user, e.g. `California`.

2276 

2277 - `timezone: optional string`

2278 

2279 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

2280 

2281 - `type: optional "approximate"`

2282 

2283 The type of location approximation. Always `approximate`.

2284 

2285 - `"approximate"`

2286 

2287 - `Mcp object { server_label, type, allowed_tools, 7 more }`

2288 

2289 Give the model access to additional tools via remote Model Context Protocol

2290 (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp).

2291 

2292 - `server_label: string`

2293 

2294 A label for this MCP server, used to identify it in tool calls.

2295 

2296 - `type: "mcp"`

2297 

2298 The type of the MCP tool. Always `mcp`.

2299 

2300 - `"mcp"`

2301 

2302 - `allowed_tools: optional array of string or object { read_only, tool_names }`

2303 

2304 List of allowed tool names or a filter object.

2305 

2306 - `McpAllowedTools = array of string`

2307 

2308 A string array of allowed tool names

2309 

2310 - `McpToolFilter object { read_only, tool_names }`

2311 

2312 A filter object to specify which tools are allowed.

2313 

2314 - `read_only: optional boolean`

2315 

2316 Indicates whether or not a tool modifies data or is read-only. If an

2317 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

2318 it will match this filter.

2319 

2320 - `tool_names: optional array of string`

2321 

2322 List of allowed tool names.

2323 

2324 - `authorization: optional string`

2325 

2326 An OAuth access token that can be used with a remote MCP server, either

2327 with a custom MCP server URL or a service connector. Your application

2328 must handle the OAuth authorization flow and provide the token here.

2329 

2330 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more`

2331 

2332 Identifier for service connectors, like those available in ChatGPT. One of

2333 `server_url` or `connector_id` must be provided. Learn more about service

2334 connectors [here](/docs/guides/tools-remote-mcp#connectors).

2335 

2336 Currently supported `connector_id` values are:

2337 

2338 - Dropbox: `connector_dropbox`

2339 - Gmail: `connector_gmail`

2340 - Google Calendar: `connector_googlecalendar`

2341 - Google Drive: `connector_googledrive`

2342 - Microsoft Teams: `connector_microsoftteams`

2343 - Outlook Calendar: `connector_outlookcalendar`

2344 - Outlook Email: `connector_outlookemail`

2345 - SharePoint: `connector_sharepoint`

2346 

2347 - `"connector_dropbox"`

2348 

2349 - `"connector_gmail"`

2350 

2351 - `"connector_googlecalendar"`

2352 

2353 - `"connector_googledrive"`

2354 

2355 - `"connector_microsoftteams"`

2356 

2357 - `"connector_outlookcalendar"`

2358 

2359 - `"connector_outlookemail"`

2360 

2361 - `"connector_sharepoint"`

2362 

2363 - `defer_loading: optional boolean`

2364 

2365 Whether this MCP tool is deferred and discovered via tool search.

2366 

2367 - `headers: optional map[string]`

2368 

2369 Optional HTTP headers to send to the MCP server. Use for authentication

2370 or other purposes.

2371 

2372 - `require_approval: optional object { always, never } or "always" or "never"`

2373 

2374 Specify which of the MCP server's tools require approval.

2375 

2376 - `McpToolApprovalFilter object { always, never }`

2377 

2378 Specify which of the MCP server's tools require approval. Can be

2379 `always`, `never`, or a filter object associated with tools

2380 that require approval.

2381 

2382 - `always: optional object { read_only, tool_names }`

2383 

2384 A filter object to specify which tools are allowed.

2385 

2386 - `read_only: optional boolean`

2387 

2388 Indicates whether or not a tool modifies data or is read-only. If an

2389 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

2390 it will match this filter.

2391 

2392 - `tool_names: optional array of string`

2393 

2394 List of allowed tool names.

2395 

2396 - `never: optional object { read_only, tool_names }`

2397 

2398 A filter object to specify which tools are allowed.

2399 

2400 - `read_only: optional boolean`

2401 

2402 Indicates whether or not a tool modifies data or is read-only. If an

2403 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

2404 it will match this filter.

2405 

2406 - `tool_names: optional array of string`

2407 

2408 List of allowed tool names.

2409 

2410 - `McpToolApprovalSetting = "always" or "never"`

2411 

2412 Specify a single approval policy for all tools. One of `always` or

2413 `never`. When set to `always`, all tools will require approval. When

2414 set to `never`, all tools will not require approval.

2415 

2416 - `"always"`

2417 

2418 - `"never"`

2419 

2420 - `server_description: optional string`

2421 

2422 Optional description of the MCP server, used to provide more context.

2423 

2424 - `server_url: optional string`

2425 

2426 The URL for the MCP server. One of `server_url` or `connector_id` must be

2427 provided.

2428 

2429 - `CodeInterpreter object { container, type }`

2430 

2431 A tool that runs Python code to help generate a response to a prompt.

2432 

2433 - `container: string or object { type, file_ids, memory_limit, network_policy }`

2434 

2435 The code interpreter container. Can be a container ID or an object that

2436 specifies uploaded file IDs to make available to your code, along with an

2437 optional `memory_limit` setting.

2438 

2439 - `string`

2440 

2441 The container ID.

2442 

2443 - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }`

2444 

2445 Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

2446 

2447 - `type: "auto"`

2448 

2449 Always `auto`.

2450 

2451 - `"auto"`

2452 

2453 - `file_ids: optional array of string`

2454 

2455 An optional list of uploaded files to make available to your code.

2456 

2457 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

2458 

2459 The memory limit for the code interpreter container.

2460 

2461 - `"1g"`

2462 

2463 - `"4g"`

2464 

2465 - `"16g"`

2466 

2467 - `"64g"`

2468 

2469 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

2470 

2471 Network access policy for the container.

2472 

2473 - `ContainerNetworkPolicyDisabled object { type }`

2474 

2475 - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }`

2476 

2477 - `type: "code_interpreter"`

2478 

2479 The type of the code interpreter tool. Always `code_interpreter`.

2480 

2481 - `"code_interpreter"`

2482 

2483 - `ImageGeneration object { type, action, background, 9 more }`

2484 

2485 A tool that generates images using the GPT image models.

2486 

2487 - `type: "image_generation"`

2488 

2489 The type of the image generation tool. Always `image_generation`.

2490 

2491 - `"image_generation"`

2492 

2493 - `action: optional "generate" or "edit" or "auto"`

2494 

2495 Whether to generate a new image or edit an existing image. Default: `auto`.

2496 

2497 - `"generate"`

2498 

2499 - `"edit"`

2500 

2501 - `"auto"`

2502 

2503 - `background: optional "transparent" or "opaque" or "auto"`

2504 

2505 Background type for the generated image. One of `transparent`,

2506 `opaque`, or `auto`. Default: `auto`.

2507 

2508 - `"transparent"`

2509 

2510 - `"opaque"`

2511 

2512 - `"auto"`

2513 

2514 - `input_fidelity: optional "high" or "low"`

2515 

2516 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

2517 

2518 - `"high"`

2519 

2520 - `"low"`

2521 

2522 - `input_image_mask: optional object { file_id, image_url }`

2523 

2524 Optional mask for inpainting. Contains `image_url`

2525 (string, optional) and `file_id` (string, optional).

2526 

2527 - `file_id: optional string`

2528 

2529 File ID for the mask image.

2530 

2531 - `image_url: optional string`

2532 

2533 Base64-encoded mask image.

2534 

2535 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"`

2536 

2537 The image generation model to use. Default: `gpt-image-1`.

2538 

2539 - `string`

2540 

2541 - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"`

2542 

2543 The image generation model to use. Default: `gpt-image-1`.

2544 

2545 - `"gpt-image-1"`

2546 

2547 - `"gpt-image-1-mini"`

2548 

2549 - `"gpt-image-1.5"`

2550 

2551 - `moderation: optional "auto" or "low"`

2552 

2553 Moderation level for the generated image. Default: `auto`.

2554 

2555 - `"auto"`

2556 

2557 - `"low"`

2558 

2559 - `output_compression: optional number`

2560 

2561 Compression level for the output image. Default: 100.

2562 

2563 - `output_format: optional "png" or "webp" or "jpeg"`

2564 

2565 The output format of the generated image. One of `png`, `webp`, or

2566 `jpeg`. Default: `png`.

2567 

2568 - `"png"`

2569 

2570 - `"webp"`

2571 

2572 - `"jpeg"`

2573 

2574 - `partial_images: optional number`

2575 

2576 Number of partial images to generate in streaming mode, from 0 (default value) to 3.

2577 

2578 - `quality: optional "low" or "medium" or "high" or "auto"`

2579 

2580 The quality of the generated image. One of `low`, `medium`, `high`,

2581 or `auto`. Default: `auto`.

2582 

2583 - `"low"`

2584 

2585 - `"medium"`

2586 

2587 - `"high"`

2588 

2589 - `"auto"`

2590 

2591 - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

2592 

2593 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

2594 

2595 - `string`

2596 

2597 - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"`

2598 

2599 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

2600 

2601 - `"1024x1024"`

2602 

2603 - `"1024x1536"`

2604 

2605 - `"1536x1024"`

2606 

2607 - `"auto"`

2608 

2609 - `LocalShell object { type }`

2610 

2611 A tool that allows the model to execute shell commands in a local environment.

2612 

2613 - `type: "local_shell"`

2614 

2615 The type of the local shell tool. Always `local_shell`.

2616 

2617 - `"local_shell"`

2618 

2619 - `Shell object { type, environment }`

2620 

2621 A tool that allows the model to execute shell commands.

2622 

2623 - `type: "shell"`

2624 

2625 The type of the shell tool. Always `shell`.

2626 

2627 - `"shell"`

2628 

2629 - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference`

2630 

2631 - `ContainerAuto object { type, file_ids, memory_limit, 2 more }`

2632 

2633 - `LocalEnvironment object { type, skills }`

2634 

2635 - `ContainerReference object { container_id, type }`

2636 

2637 - `Custom object { name, type, defer_loading, 2 more }`

2638 

2639 A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

2640 

2641 - `name: string`

2642 

2643 The name of the custom tool, used to identify it in tool calls.

2644 

2645 - `type: "custom"`

2646 

2647 The type of the custom tool. Always `custom`.

2648 

2649 - `"custom"`

2650 

2651 - `defer_loading: optional boolean`

2652 

2653 Whether this tool should be deferred and discovered via tool search.

2654 

2655 - `description: optional string`

2656 

2657 Optional description of the custom tool, used to provide more context.

2658 

2659 - `format: optional CustomToolInputFormat`

2660 

2661 The input format for the custom tool. Default is unconstrained text.

2662 

2663 - `Namespace object { description, name, tools, type }`

2664 

2665 Groups function/custom tools under a shared namespace.

2666 

2667 - `description: string`

2668 

2669 A description of the namespace shown to the model.

2670 

2671 - `name: string`

2672 

2673 The namespace name used in tool calls (for example, `crm`).

2674 

2675 - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }`

2676 

2677 The function/custom tools available inside this namespace.

2678 

2679 - `Function object { name, type, defer_loading, 3 more }`

2680 

2681 - `name: string`

2682 

2683 - `type: "function"`

2684 

2685 - `"function"`

2686 

2687 - `defer_loading: optional boolean`

2688 

2689 Whether this function should be deferred and discovered via tool search.

2690 

2691 - `description: optional string`

2692 

2693 - `parameters: optional unknown`

2694 

2695 - `strict: optional boolean`

2696 

2697 - `Custom object { name, type, defer_loading, 2 more }`

2698 

2699 A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

2700 

2701 - `name: string`

2702 

2703 The name of the custom tool, used to identify it in tool calls.

2704 

2705 - `type: "custom"`

2706 

2707 The type of the custom tool. Always `custom`.

2708 

2709 - `"custom"`

2710 

2711 - `defer_loading: optional boolean`

2712 

2713 Whether this tool should be deferred and discovered via tool search.

2714 

2715 - `description: optional string`

2716 

2717 Optional description of the custom tool, used to provide more context.

2718 

2719 - `format: optional CustomToolInputFormat`

2720 

2721 The input format for the custom tool. Default is unconstrained text.

2722 

2723 - `type: "namespace"`

2724 

2725 The type of the tool. Always `namespace`.

2726 

2727 - `"namespace"`

2728 

2729 - `ToolSearch object { type, description, execution, parameters }`

2730 

2731 Hosted or BYOT tool search configuration for deferred tools.

2732 

2733 - `type: "tool_search"`

2734 

2735 The type of the tool. Always `tool_search`.

2736 

2737 - `"tool_search"`

2738 

2739 - `description: optional string`

2740 

2741 Description shown to the model for a client-executed tool search tool.

2742 

2743 - `execution: optional "server" or "client"`

2744 

2745 Whether tool search is executed by the server or by the client.

2746 

2747 - `"server"`

2748 

2749 - `"client"`

2750 

2751 - `parameters: optional unknown`

2752 

2753 Parameter schema for a client-executed tool search tool.

2754 

2755 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }`

2756 

2757 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

2758 

2759 - `type: "web_search_preview" or "web_search_preview_2025_03_11"`

2760 

2761 The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.

2762 

2763 - `"web_search_preview"`

2764 

2765 - `"web_search_preview_2025_03_11"`

2766 

2767 - `search_content_types: optional array of "text" or "image"`

2768 

2769 - `"text"`

2770 

2771 - `"image"`

2772 

2773 - `search_context_size: optional "low" or "medium" or "high"`

2774 

2775 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

2776 

2777 - `"low"`

2778 

2779 - `"medium"`

2780 

2781 - `"high"`

2782 

2783 - `user_location: optional object { type, city, country, 2 more }`

2784 

2785 The user's location.

2786 

2787 - `type: "approximate"`

2788 

2789 The type of location approximation. Always `approximate`.

2790 

2791 - `"approximate"`

2792 

2793 - `city: optional string`

2794 

2795 Free text input for the city of the user, e.g. `San Francisco`.

2796 

2797 - `country: optional string`

2798 

2799 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

2800 

2801 - `region: optional string`

2802 

2803 Free text input for the region of the user, e.g. `California`.

2804 

2805 - `timezone: optional string`

2806 

2807 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

2808 

2809 - `ApplyPatch object { type }`

2810 

2811 Allows the assistant to create, delete, or update files using unified diffs.

2812 

2813 - `type: "apply_patch"`

2814 

2815 The type of the tool. Always `apply_patch`.

2816 

2817 - `"apply_patch"`

2818 

2819 - `type: "additional_tools"`

2820 

2821 The item type. Always `additional_tools`.

2822 

2823 - `"additional_tools"`

2824 

2825 - `id: optional string`

2826 

2827 The unique ID of this additional tools item.

2828 

2085 - `Reasoning object { id, summary, type, 3 more }`2829 - `Reasoning object { id, summary, type, 3 more }`

2086 2830 

2087 A description of the chain of thought used by a reasoning model while generating2831 A description of the chain of thought used by a reasoning model while generating

590 590 

591 The unique ID of the web search tool call.591 The unique ID of the web search tool call.

592 592 

593 - `action: object { query, type, queries, sources } or object { type, url } or object { pattern, type, url }`593 - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }`

594 594 

595 An object describing the specific action taken in this web search call.595 An object describing the specific action taken in this web search call.

596 Includes details on how the model used the web (search, open_page, find_in_page).596 Includes details on how the model used the web (search, open_page, find_in_page).

597 597 

598 - `Search object { query, type, queries, sources }`598 - `Search object { type, queries, query, sources }`

599 599 

600 Action type "search" - Performs a web search query.600 Action type "search" - Performs a web search query.

601 601 

602 - `query: string`

603 

604 [DEPRECATED] The search query.

605 

606 - `type: "search"`602 - `type: "search"`

607 603 

608 The action type.604 The action type.

613 609 

614 The search queries.610 The search queries.

615 611 

612 - `query: optional string`

613 

614 The search query.

615 

616 - `sources: optional array of object { type, url }`616 - `sources: optional array of object { type, url }`

617 617 

618 The sources used in the search.618 The sources used in the search.

2113 2113 

2114 The identifier of the actor that created the item.2114 The identifier of the actor that created the item.

2115 2115 

2116 - `AdditionalTools object { id, role, tools, type }`

2117 

2118 - `id: string`

2119 

2120 The unique ID of the additional tools item.

2121 

2122 - `role: "unknown" or "user" or "assistant" or 5 more`

2123 

2124 The role that provided the additional tools.

2125 

2126 - `"unknown"`

2127 

2128 - `"user"`

2129 

2130 - `"assistant"`

2131 

2132 - `"system"`

2133 

2134 - `"critic"`

2135 

2136 - `"discriminator"`

2137 

2138 - `"developer"`

2139 

2140 - `"tool"`

2141 

2142 - `tools: array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more`

2143 

2144 The additional tool definitions made available at this item.

2145 

2146 - `Function object { name, parameters, strict, 3 more }`

2147 

2148 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

2149 

2150 - `name: string`

2151 

2152 The name of the function to call.

2153 

2154 - `parameters: map[unknown]`

2155 

2156 A JSON schema object describing the parameters of the function.

2157 

2158 - `strict: boolean`

2159 

2160 Whether to enforce strict parameter validation. Default `true`.

2161 

2162 - `type: "function"`

2163 

2164 The type of the function tool. Always `function`.

2165 

2166 - `"function"`

2167 

2168 - `defer_loading: optional boolean`

2169 

2170 Whether this function is deferred and loaded via tool search.

2171 

2172 - `description: optional string`

2173 

2174 A description of the function. Used by the model to determine whether or not to call the function.

2175 

2176 - `FileSearch object { type, vector_store_ids, filters, 2 more }`

2177 

2178 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

2179 

2180 - `type: "file_search"`

2181 

2182 The type of the file search tool. Always `file_search`.

2183 

2184 - `"file_search"`

2185 

2186 - `vector_store_ids: array of string`

2187 

2188 The IDs of the vector stores to search.

2189 

2190 - `filters: optional ComparisonFilter or CompoundFilter`

2191 

2192 A filter to apply.

2193 

2194 - `ComparisonFilter object { key, type, value }`

2195 

2196 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

2197 

2198 - `CompoundFilter object { filters, type }`

2199 

2200 Combine multiple filters using `and` or `or`.

2201 

2202 - `max_num_results: optional number`

2203 

2204 The maximum number of results to return. This number should be between 1 and 50 inclusive.

2205 

2206 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }`

2207 

2208 Ranking options for search.

2209 

2210 - `hybrid_search: optional object { embedding_weight, text_weight }`

2211 

2212 Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

2213 

2214 - `embedding_weight: number`

2215 

2216 The weight of the embedding in the reciprocal ranking fusion.

2217 

2218 - `text_weight: number`

2219 

2220 The weight of the text in the reciprocal ranking fusion.

2221 

2222 - `ranker: optional "auto" or "default-2024-11-15"`

2223 

2224 The ranker to use for the file search.

2225 

2226 - `"auto"`

2227 

2228 - `"default-2024-11-15"`

2229 

2230 - `score_threshold: optional number`

2231 

2232 The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

2233 

2234 - `Computer object { type }`

2235 

2236 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2237 

2238 - `type: "computer"`

2239 

2240 The type of the computer tool. Always `computer`.

2241 

2242 - `"computer"`

2243 

2244 - `ComputerUsePreview object { display_height, display_width, environment, type }`

2245 

2246 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2247 

2248 - `display_height: number`

2249 

2250 The height of the computer display.

2251 

2252 - `display_width: number`

2253 

2254 The width of the computer display.

2255 

2256 - `environment: "windows" or "mac" or "linux" or 2 more`

2257 

2258 The type of computer environment to control.

2259 

2260 - `"windows"`