go/resources/batches/methods/retrieve/index.md +0 −270 deleted
File Deleted View Diff
1## Retrieve batch
2
3`client.Batches.Get(ctx, batchID) (*Batch, error)`
4
5**get** `/batches/{batch_id}`
6
7Retrieves a batch.
8
9### Parameters
10
11- `batchID string`
12
13### Returns
14
15- `type Batch struct{…}`
16
17 - `ID string`
18
19 - `CompletionWindow string`
20
21 The time frame within which the batch should be processed.
22
23 - `CreatedAt int64`
24
25 The Unix timestamp (in seconds) for when the batch was created.
26
27 - `Endpoint string`
28
29 The OpenAI API endpoint used by the batch.
30
31 - `InputFileID string`
32
33 The ID of the input file for the batch.
34
35 - `Object Batch`
36
37 The object type, which is always `batch`.
38
39 - `const BatchBatch Batch = "batch"`
40
41 - `Status BatchStatus`
42
43 The current status of the batch.
44
45 - `const BatchStatusValidating BatchStatus = "validating"`
46
47 - `const BatchStatusFailed BatchStatus = "failed"`
48
49 - `const BatchStatusInProgress BatchStatus = "in_progress"`
50
51 - `const BatchStatusFinalizing BatchStatus = "finalizing"`
52
53 - `const BatchStatusCompleted BatchStatus = "completed"`
54
55 - `const BatchStatusExpired BatchStatus = "expired"`
56
57 - `const BatchStatusCancelling BatchStatus = "cancelling"`
58
59 - `const BatchStatusCancelled BatchStatus = "cancelled"`
60
61 - `CancelledAt int64`
62
63 The Unix timestamp (in seconds) for when the batch was cancelled.
64
65 - `CancellingAt int64`
66
67 The Unix timestamp (in seconds) for when the batch started cancelling.
68
69 - `CompletedAt int64`
70
71 The Unix timestamp (in seconds) for when the batch was completed.
72
73 - `ErrorFileID string`
74
75 The ID of the file containing the outputs of requests with errors.
76
77 - `Errors BatchErrors`
78
79 - `Data []BatchError`
80
81 - `Code string`
82
83 An error code identifying the error type.
84
85 - `Line int64`
86
87 The line number of the input file where the error occurred, if applicable.
88
89 - `Message string`
90
91 A human-readable message providing more details about the error.
92
93 - `Param string`
94
95 The name of the parameter that caused the error, if applicable.
96
97 - `Object string`
98
99 The object type, which is always `list`.
100
101 - `ExpiredAt int64`
102
103 The Unix timestamp (in seconds) for when the batch expired.
104
105 - `ExpiresAt int64`
106
107 The Unix timestamp (in seconds) for when the batch will expire.
108
109 - `FailedAt int64`
110
111 The Unix timestamp (in seconds) for when the batch failed.
112
113 - `FinalizingAt int64`
114
115 The Unix timestamp (in seconds) for when the batch started finalizing.
116
117 - `InProgressAt int64`
118
119 The Unix timestamp (in seconds) for when the batch started processing.
120
121 - `Metadata Metadata`
122
123 Set of 16 key-value pairs that can be attached to an object. This can be
124 useful for storing additional information about the object in a structured
125 format, and querying for objects via API or the dashboard.
126
127 Keys are strings with a maximum length of 64 characters. Values are strings
128 with a maximum length of 512 characters.
129
130 - `Model string`
131
132 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
133 offers a wide range of models with different capabilities, performance
134 characteristics, and price points. Refer to the [model
135 guide](https://platform.openai.com/docs/models) to browse and compare available models.
136
137 - `OutputFileID string`
138
139 The ID of the file containing the outputs of successfully executed requests.
140
141 - `RequestCounts BatchRequestCounts`
142
143 The request counts for different statuses within the batch.
144
145 - `Completed int64`
146
147 Number of requests that have been completed successfully.
148
149 - `Failed int64`
150
151 Number of requests that have failed.
152
153 - `Total int64`
154
155 Total number of requests in the batch.
156
157 - `Usage BatchUsage`
158
159 Represents token usage details including input tokens, output tokens, a
160 breakdown of output tokens, and the total tokens used. Only populated on
161 batches created after September 7, 2025.
162
163 - `InputTokens int64`
164
165 The number of input tokens.
166
167 - `InputTokensDetails BatchUsageInputTokensDetails`
168
169 A detailed breakdown of the input tokens.
170
171 - `CachedTokens int64`
172
173 The number of tokens that were retrieved from the cache. [More on
174 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
175
176 - `OutputTokens int64`
177
178 The number of output tokens.
179
180 - `OutputTokensDetails BatchUsageOutputTokensDetails`
181
182 A detailed breakdown of the output tokens.
183
184 - `ReasoningTokens int64`
185
186 The number of reasoning tokens.
187
188 - `TotalTokens int64`
189
190 The total number of tokens used.
191
192### Example
193
194```go
195package main
196
197import (
198 "context"
199 "fmt"
200
201 "github.com/openai/openai-go"
202 "github.com/openai/openai-go/option"
203)
204
205func main() {
206 client := openai.NewClient(
207 option.WithAPIKey("My API Key"),
208 )
209 batch, err := client.Batches.Get(context.TODO(), "batch_id")
210 if err != nil {
211 panic(err.Error())
212 }
213 fmt.Printf("%+v\n", batch.ID)
214}
215```
216
217#### Response
218
219```json
220{
221 "id": "id",
222 "completion_window": "completion_window",
223 "created_at": 0,
224 "endpoint": "endpoint",
225 "input_file_id": "input_file_id",
226 "object": "batch",
227 "status": "validating",
228 "cancelled_at": 0,
229 "cancelling_at": 0,
230 "completed_at": 0,
231 "error_file_id": "error_file_id",
232 "errors": {
233 "data": [
234 {
235 "code": "code",
236 "line": 0,
237 "message": "message",
238 "param": "param"
239 }
240 ],
241 "object": "object"
242 },
243 "expired_at": 0,
244 "expires_at": 0,
245 "failed_at": 0,
246 "finalizing_at": 0,
247 "in_progress_at": 0,
248 "metadata": {
249 "foo": "string"
250 },
251 "model": "model",
252 "output_file_id": "output_file_id",
253 "request_counts": {
254 "completed": 0,
255 "failed": 0,
256 "total": 0
257 },
258 "usage": {
259 "input_tokens": 0,
260 "input_tokens_details": {
261 "cached_tokens": 0
262 },
263 "output_tokens": 0,
264 "output_tokens_details": {
265 "reasoning_tokens": 0
266 },
267 "total_tokens": 0
268 }
269}
270```