1.  [Documentation](/en/docs)
2.  [API](/en/docs/api/quickstart)
3.  Runs

# Runs

How a Run is created, how you know it finished and how to retry it without being charged twice.

## Immediate answer or 202

`POST /templates/{id}/runs` waits up to 30 seconds for the Run to finish. If it does, you get `201` with the finished Run and its output is ready to download. Past 30 seconds you get `202`, a `Location` header pointing at the Run and a `Retry-After` header telling you how long to wait before polling.

A CSV upload can send `delimiter` and `header_row` next to `file`, overriding the sniffed defaults for that one Run:

    curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -F "file=@/path/to/your/file.csv" \
      -F "delimiter=;" \
      -F "header_row=0"

Copy

If a column was renamed, the Run answers [TEMPLATE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#TEMPLATE_COLUMNS_MISSING) with `missing_columns`: each column the Template reads, with the file’s columns to choose from. Nothing is charged. Retry with `column_mapping`, a JSON object `{"file column": "Template column"}`, for that one Run only; it is never saved. A column that differs only in case, spaces or underscores is matched on its own and reported as a [COLUMN\_MATCHED](/en/docs/api/errors-and-limits#COLUMN_MATCHED) warning.

## Check the status

`GET /runs/{id}` answers the Run with its status: `running`, `succeeded` or `failed`. Poll it, waiting as long as `Retry-After` says, until it settles. Every field is in the [API reference](/en/docs/api/reference). Rather than polling, add a [Webhook](/en/docs/api/webhooks) and DocTransform tells you when a Run finishes.

    curl "https://doctransform.xyz/api/v1/runs/run_abc" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Copy

## Download the result

`GET /runs/{id}/output` downloads the file. A finished Run’s output stays available for **30 minutes**, or for **3 days** when a Webhook receives the Run; after that, or for an unknown id, it answers [RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND).

    curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -o result.csv

Copy

## When a file cannot run

A Run has no running Dataset: every file it needs comes in the request. A request that cannot run is refused up front, never a failed Run to poll for.

*   A file missing a column the Template needs: [TEMPLATE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#TEMPLATE_COLUMNS_MISSING).
*   Several `file` parts to a Template without an Append Step: [TEMPLATE\_TAKES\_ONE\_FILE](/en/docs/api/errors-and-limits#TEMPLATE_TAKES_ONE_FILE). More parts than your plan allows: [FILE\_COUNT\_LIMIT\_EXCEEDED](/en/docs/api/errors-and-limits#FILE_COUNT_LIMIT_EXCEEDED).
*   A file that is this Template’s own output: [TEMPLATE\_OUTPUT\_AS\_SOURCE](/en/docs/api/errors-and-limits#TEMPLATE_OUTPUT_AS_SOURCE). Nothing is charged.
*   A Run that succeeds can still carry a `warnings` list, one [APPEND\_LOCALE\_DISAGREEMENT](/en/docs/api/errors-and-limits#APPEND_LOCALE_DISAGREEMENT) entry per part whose numbers read differently under its own separators. Nothing is converted.
*   A Template with a Summary sheet adds a warning when the sheet cannot be written, because the Template is not Excel: [SUMMARY\_SHEET\_NOT\_WRITTEN](/en/docs/api/errors-and-limits#SUMMARY_SHEET_NOT_WRITTEN). It adds another when the sheet has more than half as many rows as the data: [SUMMARY\_SHEET\_ONE\_GROUP\_PER\_ROW](/en/docs/api/errors-and-limits#SUMMARY_SHEET_ONE_GROUP_PER_ROW). A Summary sheet that cannot be built fails the Run with [SUMMARY\_SHEET\_BROKEN](/en/docs/api/errors-and-limits#SUMMARY_SHEET_BROKEN). That failed Run is not charged.

A Template that names a system it uploads to adds a `destination_check` to the Run once it succeeds: `passed`, `rows_checked`, `rows_failing` and one `reasons` entry per failing rule, with its `rule_id`, the `field` header, the `outcome`, the `count` and a fixed `message`. It holds counts only, never a value from your file. A failing check does not fail the Run: the status, the status code and the charge are those of any succeeded Run, so a script can branch on `passed` before it uploads. It is `null` when the Template names no system and until the Run succeeds.

A succeeded Run also returns a `change_report` beside the output, one file or the ZIP of Split Parts: English `lines` with the rows changed per column, and the counts in `steps`. It holds counts and headers, never a value from your file. `null` until the Run succeeds.

Every succeeded Run keeps its counts on the Template. On the next Run, each step of the `change_report` carries last time’s counts in `previous`, matched by `step_key`; a new or edited step has `new_or_changed` instead. A count at least twice or at most half of last time’s, and at least 10 rows apart, is listed in `swings` and adds a [CHANGE\_COUNT\_SWING](/en/docs/api/errors-and-limits#CHANGE_COUNT_SWING) warning to `warnings`. It never fails a Run. An Excel Run gains a last `Changes` tab; a CSV, JSON or XML Run returns your file as it is, not zipped like the app’s `.zip`, unless the Template has a File Split.

A Template with a File Split writes its output as Split Parts. A Run that writes two or more returns one `application/zip` named `<name>.zip` with one file per part; a Run that writes one part returns that file plain. `output.split_parts` counts the files, `null` without a File Split. A split into more than 100 parts fails the Run with [FILE\_SPLIT\_TOO\_MANY\_PARTS](/en/docs/api/errors-and-limits#FILE_SPLIT_TOO_MANY_PARTS)and writes no file.

A Template with date steps needs no extra parameter. In a Time between dates step, an empty start or end reads as the UTC date the Run was created, so a replay of the same request counts to the same day. In a Date part step, month and weekday names come out in the step’s own `name_language`.

## Send a Join File

A Template with a Join Step on a file sent with each Run needs that file in the request. Send it as one more `file` part: there is no field name to choose and no order to keep. The Run matches each part to the main file or to a Join File by the fit of its header, so the parts can come in any order:

    curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -F "file=@/path/to/orders.csv" \
      -F "file=@/path/to/catalog.csv"

Copy

*   A Join File that was not sent: [JOIN\_FILE\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_MISSING). A part that lacks columns the step needs, including a main file sent where a Join File belongs: [JOIN\_FILE\_COLUMNS\_MISSING](/en/docs/api/errors-and-limits#JOIN_FILE_COLUMNS_MISSING).
*   Two parts that fit the same file equally well and cannot be told apart: [RUN\_FILES\_AMBIGUOUS](/en/docs/api/errors-and-limits#RUN_FILES_AMBIGUOUS).
*   A Template that joins a saved reference table that no longer exists, deleted tables included: [REFERENCE\_TABLE\_NOT\_FOUND](/en/docs/api/errors-and-limits#REFERENCE_TABLE_NOT_FOUND), with the table’s name in the message. A column the step reads that the table no longer has: [REFERENCE\_TABLE\_COLUMN\_MISSING](/en/docs/api/errors-and-limits#REFERENCE_TABLE_COLUMN_MISSING).

A Run that succeeds can carry join entries in `warnings`: [JOIN\_UNMATCHED\_ROWS](/en/docs/api/errors-and-limits#JOIN_UNMATCHED_ROWS) when rows found no match, [JOIN\_REPEATED\_KEYS](/en/docs/api/errors-and-limits#JOIN_REPEATED_KEYS) when the table repeats a key and each uses its first row, [JOIN\_CLOSE\_MATCHES](/en/docs/api/errors-and-limits#JOIN_CLOSE_MATCHES) when rows were matched to a close spelling, and [JOIN\_CLOSE\_MATCH\_LIMIT](/en/docs/api/errors-and-limits#JOIN_CLOSE_MATCH_LIMIT) when close matching stopped at its limit. Each carries counts. The few example values are in the `201` response that started the Run only: `GET /runs/{id}` and a replay with the same `Idempotency-Key` answer `"sample": null` with the counts alone.

The Run also lists `reference_tables`: the id, name, last update and row count of each table it read, as they were when it started. A table replaced while the Run was going does not change it.

## Retry with Idempotency-Key

Send an `Idempotency-Key` header with the create request. A network retry of the same request replays the Run already started for that key instead of starting, and charging, a second one:

    curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
      -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
      -H "Idempotency-Key: 3f2b9c1e-7a54-4d0e-9b61-0c8d5e2a41f7" \
      -F "file=@/path/to/your/file.csv"

Copy

Reusing a key with a different request answers [IDEMPOTENCY\_KEY\_REUSED](/en/docs/api/errors-and-limits#IDEMPOTENCY_KEY_REUSED). A Run that settles as [RUN\_INTERRUPTED](/en/docs/api/errors-and-limits#RUN_INTERRUPTED) or [RUN\_TIMEOUT](/en/docs/api/errors-and-limits#RUN_TIMEOUT), or whose id answers [RUN\_NOT\_FOUND](/en/docs/api/errors-and-limits#RUN_NOT_FOUND), is safe to resubmit with the same key.
