Transmutify Docs
GEThttps://api.transmutify.io/v1/transformations/{transformationRun}

Retrieve the current state of a transformation run

Returns the run's status, mapping rule, and any failure details. Poll this endpoint to track run progress.

Requires a bearer token. Learn more about authentication

Path parameters

transformationRunstring required

The transformation run UUID

Responses

idstring required

Stable UUID of the transformation run. Use this in subsequent requests against the run.

statusstring required

Current lifecycle status (e.g. `awaiting_upload`, `queued`, `processing`, `completed`, `failed`).

terminalboolean required

Whether this run has reached a final state.

stagestring required

Current stage of the run (`review` while hosted review is active, `final` once approved).

schema_idstring required

UUID of the schema this run targets.

provider_idstring | null required

UUID of the selected AI provider. Null when no provider was selected for a structured-file run.

dry_runboolean required

Whether this is a dry run (no AI provider invoked, synthetic input data used).

input_sourcestring required

Input source for this run (`upload`, `raw`, or `image`).

metadataobject | null required

Caller-defined metadata submitted when the transformation was initialized.

review_urlstring | null required

Signed hosted-review URL for end-user review, when review is available.

review_statestring | null required

Current hosted-review state (`active`, `canceled`, `approved`, `expired`), or null when no review exists.

review_canceled_atstring | null required

ISO-8601 UTC timestamp the reviewer first canceled, or null otherwise.

review_approved_atstring | null required

ISO-8601 UTC timestamp the reviewer approved, or null otherwise.

review_expires_atstring | null required

ISO-8601 UTC timestamp after which the hosted review page shows an expired state, or null when no review exists.

output_formatstring required

Output artifact format requested when the run was initialized (`json` by default).

mapping_ruleobject | null required

Currently effective mapping rule keyed by target field name; values are the source CSV column header or null.

source_headersstring[] required

Column headers detected in the uploaded source file.

input_has_headerboolean | null required

Whether the uploaded source file has a real header row. False when synthetic `column_1, column_2, ...` names were generated.

total_rowsinteger | null required

Total number of rows in the source file, when known.

processed_rowsinteger required

Number of rows processed so far by the current stage.

errorobject | null required

Failure payload describing the last error, if the run is in a failed state. Null otherwise.

codestring | null required
messagestring | null required
typestring | null required
stagestring | null required
retryableboolean required
contextany[] | null | string[] required
notification_statusstring | null required

Delivery status of the successful final-output webhook (`pending`, `delivered`, `failed`), or null if none exists.

uploadobject

Pre-signed upload instructions for the source file. Present only while `status` is `awaiting_upload`.

urlstring required
headersobject required
methodstring required
expires_atstring required
download_urlstring | null required

Pre-signed URL to download the produced output file. Present only when output is ready.

file_retention_untilstring | null required

ISO-8601 UTC timestamp until which the output file is retained and downloadable. Null when no output file exists yet.

started_atstring | null required

ISO-8601 UTC timestamp the run started executing, or null if it has not started.

completed_atstring | null required

ISO-8601 UTC timestamp the run completed successfully, or null otherwise.

failed_atstring | null required

ISO-8601 UTC timestamp the run failed, or null otherwise.

cURL
curl -X GET 'https://api.transmutify.io/v1/transformations/<transformation-id>' \
  -H 'Authorization: Bearer <api-key>'
Response · 200
{
  "id": "019dc45d-3b81-7369-a776-2d95c5caab97",
  "status": "completed",
  "terminal": true,
  "stage": "final",
  "schema_id": "019dc458-710e-73a0-9b5a-bb7d6f7ddc42",
  "provider_id": "019dc459-c94a-71b4-a35f-6b6d384ef74b",
  "dry_run": false,
  "input_source": "upload",
  "metadata": {
    "external_id": "import-2026-01-15",
    "source": {
      "system": "hris",
      "batch": 42
    }
  },
  "review_url": "https://review.transmutify.io/reviews/019dc45d-3b81-7369-a776-2d95c5caab97?signature=...",
  "review_state": "approved",
  "review_canceled_at": null,
  "review_approved_at": "2026-01-15T12:30:45Z",
  "review_expires_at": "2026-01-16T12:00:00Z",
  "output_format": "json",
  "mapping_rule": {
    "employee_id": "Employee ID",
    "first_name": "First Name",
    "last_name": "Last Name",
    "work_email": "Email",
    "department": "Department",
    "start_date": "Start Date"
  },
  "source_headers": [
    "Employee ID",
    "First Name",
    "Last Name",
    "Email",
    "Department",
    "Start Date"
  ],
  "input_has_header": true,
  "total_rows": 248,
  "processed_rows": 248,
  "error": null,
  "notification_status": "delivered",
  "download_url": "https://storage.example.com/transmutify/outputs/019dc45d-3b81-7369-a776-2d95c5caab97.json?expires=1705323600",
  "file_retention_until": "2026-02-14T12:30:00Z",
  "started_at": "2026-01-15T12:30:00Z",
  "completed_at": "2026-01-15T12:31:24Z",
  "failed_at": null
}