Reading a job run

Who this is for. Anyone building or maintaining a job. Every debugging step later in this guide starts here, so learn to read a run before building anything. Afterwards you can tell from the log where a job stopped and why.

One execution of a job is a job run. The admin and the code call it a batch: Customization › Orchestration › Batch Logs lists runs newest first, with the job, what triggered it (Entity, Web, Scheduled or Job) and the status. A job's own page links to its runs with View Batch Logs.

What a run's status means

Each action in the run has its own row with a status: success, error, or skipped for a top-level action that is unpublished, a condition where no branch matched and there is no else, and a loop with no elements.

Reading a failed run

1. The trigger. Is it the record, request or schedule you expected? A run started for the wrong record answers most questions at once.
2. The first action with status error. Its output holds the message: a template error with its line, an HTTP status with the response content, a record that could not be found, a value that is not valid JSON.
3. That action's inputs as they were rendered. An HTTP request logs the method, URL, request headers, the first 5,000 characters of the body it sent, the response code and content, the retries and the duration. A Retrieve Records logs its criteria after rendering. A Create Record logs the data it parsed.
4. What is missing. Top-level actions after the failure have no rows, which is the quickest way to see where the run stopped. Nothing before the failure was undone.

A condition's row says which branch ran: Matched condition: followed by the branch's description, so describe each branch. A loop's elements have their own rows, each with a status.

Re-running a run

Rerun Batch on a run, or the mass action on the list, queues it again. A re-run is not a resume:

• It deletes the run's action results and the files in its folder, then runs the job again from the first action.
• It uses the original event (the same record, request or trigger data) with the job's actions as they are now, so fix the job first, then re-run.
• It always runs in the background, even for a synchronous job, so a web caller does not receive its answer.
• It works whatever the run's status, including a run left running by a worker that died.

Because the first actions run again, every action must be safe to run twice: see Idempotency and replay. A run whose job includes an AI agent offers two re-runs: Rerun (replay agent result), which re-presents the recorded answer at no cost, and Rerun (fresh agent run), which calls the provider again. A worked procedure is Debug a job run that failed halfway.

Which runs are kept, and for how long

The job's Batch persistence decides which runs survive their own end: Always (the default), On Error, On Success or Never. A run that is not kept is deleted as it finishes, together with its folder /hooks/<job name, slugified and cut to 30 characters>/<run id> in the file manager and every file an action saved there. Keep Always while a job is new: On Success and Never throw away the evidence you need when it fails.

Runs that are kept are deleted after 30 days by a platform task that runs at 02:10 each day. The setting is Delete batches after days under Orchestration › Configuration, from 2 to 90. Anything that must be kept longer, such as a record of what was sent to a partner, belongs in a record or file the job creates, not in its log.

Reading runs through the API

A monitor or a support script can read runs with the API, still under the old name: GET /cdna-api/hooks/batches/{job id} lists a job's runs, GET /cdna-api/hooks/batch-actions/{run id} lists its actions, and POST /cdna-api/hooks/batch/{id}/rerun re-queues one. Ask for the payloads by name, for example properties={batchActions{id,status,data,output}}. The routes, with examples, are in the job runs API reference.