Skip to main content
GET
Retrieve Batch
Retrieve the current status, progress statistics, and detailed metadata of a specific batch task. Typically used to poll whether a task has completed after creation.
FieldTypeDescription
idstringUnique identifier for the batch task
objectstringObject type, always batch
endpointstringRequest endpoint
input_file_idstringInput file ID
completion_windowstringProcessing time window
statusstringCurrent status: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled
output_file_idstring | nullOutput file ID for successful results
error_file_idstring | nullError file ID for failed results
created_atintegerCreation timestamp (Unix)
in_progress_atinteger | nullExecution start timestamp (Unix)
expires_atinteger | nullExpiration timestamp (Unix)
finalizing_atinteger | nullResult preparation start timestamp (Unix)
completed_atinteger | nullCompletion timestamp (Unix)
failed_atinteger | nullValidation failure timestamp (Unix)
cancelling_atinteger | nullCancellation request timestamp (Unix)
cancelled_atinteger | nullCancellation completion timestamp (Unix)
request_countsobjectRequest count statistics, containing completed, failed, and total
metadataobject | nullCustom metadata
For complete usage examples and polling scripts, see the Batch API Guide.
When status is completed, output_file_id contains the results file ID. When status is failed, check error_file_id for error details. If the specified batch_id does not exist, the API returns a 404 error (resource_not_found_error).

Authorizations

Authorization
string
header
required

The Authorization header expects a Bearer token. Use an MOONSHOT_API_KEY as the token. This is a server-side secret key. Generate one on the API keys page in your dashboard.

Path Parameters

batch_id
string
required

The ID of the batch task

Response

Batch task details

id
string
required

Unique identifier for the batch task

object
string
required

Object type, always batch

Example:

"batch"

endpoint
string
required

Request endpoint

input_file_id
string
required

Input file ID

completion_window
string
required

Processing time window

status
enum<string>
required

Current status: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled

Available options:
validating,
failed,
in_progress,
finalizing,
completed,
expired,
cancelling,
cancelled
created_at
integer
required

Creation timestamp (Unix)

request_counts
object
required
output_file_id
string | null

Output file ID for successful results

error_file_id
string | null

Error file ID for failed results

in_progress_at
integer | null

Execution start timestamp (Unix)

expires_at
integer | null

Expiration timestamp (Unix)

finalizing_at
integer | null

Result preparation start timestamp (Unix)

completed_at
integer | null

Completion timestamp (Unix)

failed_at
integer | null

Validation failure timestamp (Unix)

cancelling_at
integer | null

Cancellation request timestamp (Unix)

cancelled_at
integer | null

Cancellation completion timestamp (Unix)

metadata
object | null

Custom metadata