[lavanya-gunreddi]

Adds the COMPLETED API state to serverless/batch-jobs.mdx and makes the batch status description consistent across the page, as requested in review on this PR.

• Updated the lifecycle diagram to DRAFT → FINALIZED → COMPLETED / FAILED / CANCELLED, and added a COMPLETED bullet noting that individual requests may still have failed.
• Updated the FINALIZED bullet to say the batch moves to COMPLETED once requestCompleted + requestFailed equals requestTotal.
• Replaced the paragraph after the batch status example with the reviewer's wording: FINALIZED while requests process, COMPLETED when all have finished, and FAILED or CANCELLED otherwise.
• Mapped the console Completed status to the COMPLETED API status, and the console Running status to FINALIZED.

Follow-up review edits:

• Replaced the placeholder batch ID in the Step 1 and Step 4 response examples with a UUID, matching real batch IDs.
• Replaced startedAt and completedAt in the Step 5 response example with delayTime and executionTime, and explained both fields (in milliseconds).
• Documented failed batches in Error handling: the failureCode and failedAt fields, an example REQUEST_FAILURE_LIMIT response, and a table of failureCode values. Qualified the opening paragraph so it reflects that a batch stops once failures reach the request failure limit, and replaced the claim that a FAILED batch always means a systemic problem.
• Noted that requests whose handler returns an error in its output are marked COMPLETED, don't count toward the failure limit, and need their output checked.
• Noted in Cancellation that a batch cancelled before any requests start moves to CANCELLED immediately and isn't billed.

Style pass (requested in review): brought serverless/batch-jobs.mdx in line with PROMPTLESS.md and .claude/style-guide.md (including the Runpod and Google rules it references) without changing technical content.

• Headings: renamed "When to use batch vs /run" to "When to use batch jobs instead of /run" and "Monitoring batches in the console" to "Monitor batches in the console".
• Parallel options and serial comma: rewrote the Notifications intro so the three terminal states aren't chained with "or".
• Code context: added lead-in sentences before the Step 4 and Step 5 response examples, and short intros before the comparison, API reference, and limits tables.
• API endpoints and placeholders: replaced GET .../requests with the full GET /v2/ENDPOINT_ID/batch/BATCH_ID/requests path.
• Word choice and voice: changed "may" to "might" for possibility, and recast "queued batch requests may be lost" in active voice.
• Next steps: replaced the bullet list with a CardGroup of horizontal cards.
• Sentence length: split the 26-word second sentence of the introduction.

Validation: Vale (repo config, plus Promptless and Knowledge Base rules) reports 0 errors on the page; the only new findings are Readability suggestions.

Review feedback

• Applied verbatim: the reviewer's replacement paragraph after the batch status example (line 134).

• Applied for consistency with that change and the earlier COMPLETED comments: the FINALIZED bullet and the console status table.

• Applied verbatim: UUID batch ID in the Step 1 and Step 4 responses; the delayTime/executionTime sentence after the Step 5 example; the failed-batch example, failureCode table, and failedAt note; the handler-returned-error paragraph after the first Error handling paragraph; and the cancel-before-start sentence in Cancellation.

• Changed for consistency: Step 5 example values for delayTime and executionTime were chosen as plausible millisecond values. In Error handling, the opening paragraph now says a failed request doesn't fail the batch "unless failures reach the request failure limit", and the FAILED paragraph no longer says the problem is always systemic. Both previously contradicted the new REQUEST_FAILURE_LIMIT content.

• Placement: the failed-batch block comes after the FAILED paragraph. The page had no separate paragraph explaining the request failure limit, so that was the closest anchor.

• Style pass: applied the reviewer's request to conform the page to PROMPTLESS.md and .claude/style-guide.md without changing technical content. The reviewer's latest commit (the COMPLETED notification state and the request failure limit table) is preserved. Left unchanged: the billing <Note> near the top, which repeats the Billing section; removing it is a content decision rather than a style rule.

[mintlify]

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

Project	Status	Preview	Updated
runpod-docs	🟢 Ready	View Preview	Oct 27, 2026, 9:27 PM

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

[jhcipar]

We'll need one more state for COMPLETED here

[lavanya-gunreddi]

@Promptless update the "Batch lifecycle" section to add a COMPLETED API state

• Change the diagram to:
  DRAFT → FINALIZED → COMPLETED
  → FAILED
  → CANCELLED
• In the FINALIZED bullet, remove "and the API has no separate RUNNING or COMPLETED batch status". Keep the sentence about tracking progress with requestTotal, requestInProgress, requestCompleted, and requestFailed.
• Add a bullet after FINALIZED: "COMPLETED: All requests in the batch have finished. Some individual requests may have failed, so check requestFailed."
• Keep the existing style: colon after the bold state name, sentence ends with a period, no em dashes.

[jhcipar]

same thing here re: a completed state

[lavanya-gunreddi]

@Promptless Replace:
"A batch reports FINALIZED while it runs. All of its requests have finished when requestCompleted + requestFailed equals requestTotal. The status only changes again if the batch fails (FAILED) or you cancel it (CANCELLED)."

With:
"A batch reports FINALIZED while its requests are processing. When all requests have finished (requestCompleted + requestFailed equals requestTotal), the status changes to COMPLETED. To check whether a batch is done, use the status field. If the batch itself fails, the status is FAILED, and if you cancel it, the status is CANCELLED."

[promptless]

Got it, I'll replace that paragraph with your wording so the batch status description includes COMPLETED. I'll reply here once the suggestion is updated.

[promptless]

Done. This paragraph uses your wording exactly. To match it, I made two other changes on the page:

• The FINALIZED bullet in the lifecycle section says the batch moves to COMPLETED when every request has finished.
• In the console status table, Completed maps to COMPLETED and Running maps to FINALIZED. This also covers jhcipar's comment on line 222.

One question: the Notifications section says notifications are sent when a batch reaches a terminal state (FAILED or CANCELLED). Should COMPLETED be on that list too? I didn't change it because I couldn't confirm whether completed batches send a notification.

Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70

[jhcipar]

same thing for completed here

[lavanya-gunreddi]

@Promptless apply this comment

[promptless]

I'll apply the same change to the completed status on this line, matching the earlier review comment. I'll reply here once the suggestion is updated.

[promptless]

This change is already on the branch, so I didn't push anything new. In the console statuses table, the Completed row shows COMPLETED and the Running row shows FINALIZED. Both rows were updated in commit 4b93216, which was made for the earlier comment on line 44.

[promptless]

Thanks @lavanya-gunreddi. I'm updating the "Batch lifecycle" section to add the COMPLETED state, revise the diagram, and trim the FINALIZED bullet as you described, and I'll reply here when the changes are on this branch.

[promptless]

@lavanya-gunreddi I made the three edits you asked for in the "Batch lifecycle" section and pushed them to this branch in commit 53aafb9. The diagram includes COMPLETED, the FINALIZED bullet no longer says the API has no separate RUNNING or COMPLETED status, and the new COMPLETED bullet follows it.

I didn't change anything outside that section, but three other passages on the page still say a batch stays FINALIZED after all its requests finish:

• Step 3 (check progress) says a batch reports FINALIZED while it runs and only changes status if it fails or is cancelled.
• The console statuses table maps the console's Completed label to FINALIZED.
• The error handling section says a failed request leaves the batch FINALIZED.

Triggered by: #919 (review)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919
Open question: Should I update those three passages to use COMPLETED too?

[jhcipar]

we also send notifications for completed

[lavanya-gunreddi]

@Promptless replace every "batch_01j9abc123" on the page with "5af6bdb3-551f-4195-8872-bad522efbad7". Real batch IDs are UUIDs. This includes the Step 1 create response and the Step 4 batch summary response.

[lavanya-gunreddi]

@Promptless in the Step 5 response example, replace the startedAt and completedAt fields with delayTime and executionTime. After the example, add: "Each request includes delayTime (how long the request waited in the queue) and executionTime (how long it took to run), both in milliseconds.

[promptless]

In reply to this discussion

Got it: every batch_01j9abc123 on the page, including the Step 1 create response and the Step 4 batch summary response, will be replaced with 5af6bdb3-551f-4195-8872-bad522efbad7. I'll reply here when the update is on this branch.

[lavanya-gunreddi]

@Promptless in the Error handling section, after the paragraph that explains the request failure limit, add:

"A failed batch includes a failureCode that explains why it failed, and a failedAt timestamp. For example, a batch that reached the request failure limit returns:

{
  "id": "5210fe3f-ee61-4a81-bc4e-7078c955c24d",
  "endpointId": "bo3oj8kx6jz411",
  "status": "FAILED",
  "requestTotal": 12,
  "requestInProgress": 0,
  "requestCompleted": 0,
  "requestFailed": 10,
  "failureCode": "REQUEST_FAILURE_LIMIT",
  "failedAt": 1793132360580,
  "createdAt": 1793132294147,
  "name": "intentional-failed-batch-example"
}

In this example, 10 of 12 requests failed, which reached the limit, so the batch stopped and the remaining 2 requests didn't run.

failureCode	Meaning
REQUEST_FAILURE_LIMIT	Too many requests failed. Check the request-level errors, fix your handler or inputs, and submit a new batch.
ALL_BATCH_WORKERS_UNHEALTHY	No batch worker could start, so no requests ran. Check your endpoint configuration and worker logs. The response also includes failedWorkerIds.

The failedAt field is a Unix timestamp in milliseconds."

[promptless]

In reply to this discussion

Got it: the Step 5 response example will use delayTime and executionTime in place of startedAt and completedAt, and your explanation of both fields will follow the example. I'll reply here when the update is on this branch.

[lavanya-gunreddi]

@Promptless in the Error handling section, after the first paragraph, add:

"If your handler returns an error in its output instead of raising an exception, Runpod marks the request COMPLETED, not FAILED. These requests don't count toward the failure limit. To catch them, check each request's output for errors."

[promptless]

In reply to this discussion

Got it: your failed-batch explanation, example response, and failureCode table will go after the request failure limit paragraph in the Error handling section. I'll reply here when the update is on this branch.

[lavanya-gunreddi]

@Promptless in the Cancellation section, after "The batch status changes to CANCELLED once all in-progress requests have finished.", add:

"If you cancel a batch before any requests start, it moves to CANCELLED immediately and nothing is billed."

[promptless]

In reply to this discussion

Got it: your note about handler errors returned in output will go after the first paragraph of the Error handling section. I'll reply here when the update is on this branch.

[promptless]

In reply to this discussion

Got it: your sentence about cancelling a batch before any requests start will go after the CANCELLED status sentence in the Cancellation section. I'll reply here when the update is on this branch.

[promptless]

In reply to this discussion

Both example batch IDs are now 5af6bdb3-551f-4195-8872-bad522efbad7: one in the Step 1 create response and one in the Step 4 batch summary response. The page had no other instances of batch_01j9abc123.

Triggered by: #919 (comment)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919

[promptless]

In reply to this discussion

The Step 5 response example uses delayTime and executionTime in place of startedAt and completedAt. Your explanation of both fields follows the example. Your comment didn't include example values, so the example uses sample millisecond values. Replace them if you have real ones.

Triggered by: #919 (comment)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919

[promptless]

In reply to this discussion

Your failed-batch explanation, example response, failureCode table, and failedAt note are in the Error handling section. The page had no paragraph about the request failure limit, so they follow the paragraph about batches with FAILED status.

Two existing sentences contradicted your content, so I changed them:

• The opening paragraph said a failed request never fails the batch. It now says a failed request "doesn't fail the batch unless failures reach the request failure limit."
• The FAILED paragraph said the problem was systemic rather than an error in individual requests. It now says the batch stopped before it finished its requests, and tells readers to check the failureCode and the request-level errors.

The page also doesn't state the request failure limit. The example only shows 10 of 12 requests failing. You may want to add the threshold, for example in the Limits table.

Triggered by: #919 (comment)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919
Open question: Is the new wording of those two existing sentences correct?

[promptless]

In reply to this discussion

Your paragraph about handler errors returned in output is in the Error handling section as written, right after the first paragraph.

Triggered by: #919 (comment)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919

[promptless]

In reply to this discussion

Your sentence about cancelling a batch before any requests start is in the Cancellation section as written. It follows the sentence about the CANCELLED status.

Triggered by: #919 (comment)
Review: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70?org_id=org_2tHD09rTU0IcE4clVjTuJCTn0an
Docs PR: #919

[lavanya-gunreddi]

@Promptless Review serverless/batch-jobs.mdx against the rules in PROMPTLESS.md and the Runpod documentation style guide (.claude/style-guide.md), and fix anything that doesn't follow them. Don't change the technical content.

[promptless]

In reply to this discussion

Got it: I am reviewing serverless/batch-jobs.mdx against PROMPTLESS.md and .claude/style-guide.md, and I will leave the technical content unchanged. I will push the fixes to this pull request and reply here with a summary of what changed.

[promptless]

In reply to this discussion

I pushed a style-only pass on serverless/batch-jobs.mdx to this pull request. The technical content is unchanged. The fixes follow PROMPTLESS.md, .claude/style-guide.md, and the Runpod and Google rules that guide points to:

• Two headings follow the task-style heading rule: "When to use batch jobs instead of /run" and "Monitor batches in the console". No other page links to the old anchors.
• The Notifications intro no longer chains the three terminal states with "or". It lists COMPLETED, FAILED, and CANCELLED in a separate sentence.
• The Step 4 and Step 5 response examples and the three tables each have a lead-in sentence.
• The GET .../requests reference is the full path: GET /v2/ENDPOINT_ID/batch/BATCH_ID/requests.
• "May" is "might" where it describes a possibility, and one passive sentence is active.
• "Next steps" is a CardGroup linking to the same three pages.
• The long second sentence of the introduction is split in two.

Your latest edits, the COMPLETED notification state and the failure-limit table, are kept as you wrote them.

I left two things alone because changing them would change content. The billing note near the top repeats the Billing section, and numerals such as "6 have failed" stay as written.

Vale reports no errors on the page. I didn't run a Mintlify build.

Suggestion: https://app.gopromptless.ai/suggestions/d6b7a0be-7394-4edd-bee7-17372ae67c70