Create batch-jobs.mdx

[lavanya-gunreddi]

No description provided.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
runpod-docs	🟢 Ready	View Preview	Jul 9, 2026, 12:35 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jhcipar]

Reviewing against the current batch API implementation - a few spots where the doc contract and the API differ. Posting these as discussion points; happy to move the API toward the documented contract where it makes sense.

[jhcipar]

The doc shows create accepting {"name", "requests": [...]} and returning a rich object with status: "OPEN". Currently the API accepts a bare array of job inputs and returns only {id, status: "DRAFT"}. We can update the API to match this contract if needed (accept a name at create, return the full summary).

[lavanya-gunreddi]

@Promptless work on the above comment. Reference - Update the create batch request and response to match the actual API.
The current doc shows the create endpoint accepting {"name": "...", "requests": [...]} and returning a rich object with status: "OPEN". The actual API accepts a bare array of job inputs and returns only {"id": "<batch_id>", "status": "DRAFT"}. Update the request body, code example, and response example to reflect this.

[jhcipar]

Same thing as previous comment - open -> draft.

[lavanya-gunreddi]

@Promptless Replace OPEN with DRAFT everywhere in the file.
The state diagram currently reads OPEN → FINALIZED → RUNNING → COMPLETED. Change it to DRAFT → FINALIZED → RUNNING → COMPLETED. Also update any references to "open batches" to "draft batches."

[jhcipar]

The current pagination setup uses offsets/limits - eg it returns {requests, total, offset, limit, hasMore}.

[lavanya-gunreddi]

@Promptless work on the above comment - The current doc shows "nextCursor": "cursor_xyz" in the list response. The actual API returns {"requests": [...], "total": , "offset": , "limit": , "hasMore": true|false}. Update the response example and any description of how to paginate.

[jhcipar]

Just checking that this link is meant to be broken right now.

[jhcipar]

Currently we enforce this: 10 active batches per endpoint, 5,000 requests per batch, 50,000 queued per endpoint - but am adding something in beta to have it be configurable per user/org, so maybe a "contact sales" or something lever there.

[lavanya-gunreddi]

@Promptless work on the above comment - Replace the current limits with:

Active batches per endpoint: 10
Requests per batch: 5,000
Queued requests per endpoint: 50,000

Add a note below the table: "Limits are configurable for enterprise accounts. Contact sales for custom limits.

[jhcipar]

Currently we don't limit requests per call, we just have a 10 MiB body limit.

[lavanya-gunreddi]

@Promptless The doc currently states "Each call accepts up to 100 requests in a single array." Remove this. Replace with: "Request body size is limited to 10 MiB per call."

[promptless]

Thanks for the review request — we're looking into the new batch-jobs.mdx page now, checking it against the actual implementation. We'll follow up here with our findings shortly.

[promptless]

Update: we've reviewed all five requested changes to batch-jobs.mdx — the OPEN → DRAFT rename, the create request/response shape, the list/pagination response, the limits table plus enterprise note, and the per-call limit change. We're applying them now and will follow up when the updates are ready.

[promptless]

Done — OPEN has been replaced with DRAFT throughout batch-jobs.mdx. The state diagram now reads DRAFT → FINALIZED → RUNNING → COMPLETED, and all references to "open batches" now read "draft batches." Pushed to the lg-batch-jobs branch.

[promptless]

Done — the create batch request is now a bare JSON array of job inputs (the name/requests wrapper has been removed), and the response has been slimmed to {"id": "<batch_id>", "status": "DRAFT"}. The request body, code example, and response example are all updated. Pushed to lg-batch-jobs.

[promptless]

Done — the results/list response now returns {"requests": [...], "total": <n>, "offset": <n>, "limit": <n>, "hasMore": true|false} instead of nextCursor, and the pagination description has been rewritten to offset/limit-based. Pushed to lg-batch-jobs.

One follow-up: the page doesn't yet state a default or maximum for limit (the example uses 50). If you can share that value, we'll add it.

[promptless]

Done — the limits table now reads:

• Active batches per endpoint: 10
• Requests per batch: 5,000
• Queued requests per endpoint: 50,000

and a note has been added below it: "Limits are configurable for enterprise accounts. Contact sales for custom limits." Pushed to lg-batch-jobs.

[promptless]

Done — removed "Each call accepts up to 100 requests in a single array." and replaced it with "Request body size is limited to 10 MiB per call." Pushed to lg-batch-jobs.

[promptless]

One heads-up while applying the review changes: the page links to /api-reference/endpoint/batch, which doesn't exist on this branch (@jhcipar flagged this too). Since no change was requested for it, we left it as-is — worth confirming whether that API reference page is planned before merge, or repointing/removing the link.

[jhcipar]

The poll response example doesn't match what the API currently returns. GET /v2/{endpoint_id}/batch/{batch_id} returns:

• id, endpointId, status
• requestTotal, requestInProgress, requestCompleted, requestFailed
• failureCode, failedAt, failedWorkerIds (on failure)
• createdAt as epoch millis (int64), plus name if set

There's no itemCount, queuedCount, inProgressCount, completedCount, failedCount, progress, or finalizedAt.

Also, batch status today is DRAFT, FINALIZED, FAILED, or CANCELLED — there's no RUNNING state, so "status": "RUNNING" in the example doesn't reflect the API; an executing batch shows FINALIZED and progress is inferred from the request counts. Happy to add richer states/fields to the API if we'd rather keep the documented contract — otherwise the example should be updated, e.g.:

{
  "id": "batch_01j9abc123",
  "endpointId": "abc123xyz",
  "status": "FINALIZED",
  "requestTotal": 1000,
  "requestInProgress": 8,
  "requestCompleted": 244,
  "requestFailed": 6,
  "createdAt": 1783584000000
}

[lavanya-gunreddi]

@Promptless Replace the poll response example with the correct shape:
json
{
"id": "batch_01j9abc123",
"endpointId": "abc123xyz",
"status": "FINALIZED",
"requestTotal": 1000,
"requestInProgress": 8,
"requestCompleted": 244,
"requestFailed": 6,
"createdAt": 1783584000000
}
Remove RUNNING and COMPLETED from the batch state list. The actual states are DRAFT, FINALIZED, FAILED, and CANCELLED. A batch that is actively processing shows as FINALIZED — progress is tracked via requestTotal, requestInProgress, requestCompleted, and requestFailed.
Update any explanatory text around polling/monitoring to reflect that you infer progress from the request count fields, not from a RUNNING status or a progress field.

[promptless]

Thanks for the detailed corrections! I'm applying these to batch-jobs.mdx now — replacing the poll response example with the correct shape, fixing the batch state list to DRAFT, FINALIZED, FAILED, CANCELLED, and updating the polling/monitoring text to explain that progress is inferred from the request count fields rather than a RUNNING status. I'll follow up here once the changes are pushed.

[promptless]

Quick update: I've confirmed the scope of your corrections. They ripple through the batch job lifecycle diagram, the state list, the poll/summary example, and the terminal-state wording in the polling, notifications, and error-handling sections. Applying the edits across all of those now.

[promptless]

Thanks for the detailed corrections — all applied and pushed to this PR's branch. The batch states are now documented as DRAFT, FINALIZED, FAILED, and CANCELLED (RUNNING and COMPLETED removed), with an actively-processing batch shown as FINALIZED and progress tracked through the requestTotal, requestInProgress, requestCompleted, and requestFailed counts. The poll response example now matches the shape you gave (including endpointId and the epoch-millisecond createdAt), and the polling, notifications, and error-handling text now describe completion via the request counts rather than a RUNNING/COMPLETED status.

One note: since there's no COMPLETED batch state, the Notifications section was narrowed to fire only on the FAILED and CANCELLED terminal states — let us know if a notification also fires when all requests finish successfully and we'll add it back.

[celine-runpod]

Please remove all mention of the 24 hour SLA. @lavanya-gunreddi @PranjalJain-1 @jhcipar

[lavanya-gunreddi]

@Promptless remove all mention of the 24 hour SLA in the doc

[promptless]

Thanks for the request! We're on it — researching the batch jobs feature and drafting a new batch-jobs.mdx page now. We'll follow up here with the proposed documentation shortly.

[promptless]

Quick update: we found the 24-hour SLA referenced in three places in the batch jobs page (the frontmatter description, the comparison table, and a known-limitations bullet). Preparing the edits to remove all of them now.

[promptless]

Done — I removed every mention of the 24-hour SLA from the batch jobs page:

• The frontmatter description no longer claims processing "within a 24-hour SLA" — it now describes batches as processed asynchronously.
• The batch-vs-/run comparison table's latency row now reads "Multi-hour" instead of "Completed within 24h SLA".
• The known-limitations note now states that start time is not guaranteed, without referencing an SLA.

This also keeps the page consistent with the batch state model documented on the same page, which doesn't commit to a guaranteed completion time. The changes are on the lg-batch-jobs branch backing this PR.