Runs

Start a connector route run

Starts a route run and returns the accepted execution record. The optional input can carry lookup keys, batch references, dry-run flags, or caller metadata. Long-running execution is observed through the runs, events, and dead-letter endpoints.

post/routes/{routeId}/runs

Path parameters

routeIdstring uuid required

Stable identifier for a connector route.

Example:1e8ff011-2274-4f16-a7dd-bf0b4fd5262f

Stable identifier of a connector route that composes a source operation, destination operation, optional transformation, and trigger policy.

Request body

{"stackTrail":"components:schemas:StartConnectorRouteRunRequest:properties:input","oasType":"schema","type":"unknown","description":"Optional input payload, connector fields, or batch reference passed to the route.","example":{"employee_id":"E12345","batch_ref":"vault://imports/license-batches/batch-2026-06-18.csv"},"nullable":true}

dryRunboolean

Whether the run should validate and transform without committing destination writes.

invocationBindingIdstring

Stable identifier of the domain invocation binding that caused a connector call.

logicalConnectionBindingIdstring

Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.

physicalConnectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

Explicit exchange quadrant. Data direction and initiation side remain separate axes in run responses.

correlationIdstring

Caller-provided correlation id for logs, run events, and downstream traceability.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

Example request

{
  "input": {
    "batch_ref": "vault://imports/license-batches/batch-2026-06-18.csv"
  },
  "dryRun": false,
  "correlationId": "import-2026-06-18-001",
  "metadata": {
    "initiated_by": "admin@example.com"
  }
}

Response

Connector route run accepted.

runIdstring uuid required

Stable identifier for a connector route or operation run.

routeIdstring uuid

Stable identifier for a connector route.

bindingIdstring uuid

Stable identifier for a connector operation binding.

connectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

invocationBindingIdstring

Stable identifier of the domain invocation binding that caused a connector call.

logicalConnectionBindingIdstring

Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.

physicalConnectorInstanceIdstring uuid

Stable platform identifier for a configured connector instance.

Explicit exchange quadrant. Data direction and initiation side remain separate axes in run responses.

dataDirection'INBOUND' | 'OUTBOUND' | 'BIDIRECTIONAL'

Direction of data movement relative to the platform operating the connector.

initiationSide'PLATFORM' | 'EXTERNAL' | 'SUBSCRIPTION_CALLBACK' | 'BIDIRECTIONAL_SYNC'

Side that initiated the exchange.

connectorResourceIdstring uuid

Stable identifier for a resource attached to a connector instance.

Reusable operation taxonomy shared by connectors, inventory, policy, and workflows. The operation kind is logical; connector-local details live in operationName.

Mechanism that initiated the run.

Execution status of a route run or connector operation run.

startedAtstring date-time required

Timestamp when execution started.

finishedAtstring date-time

Timestamp when execution finished, if complete.

itemCountinteger

Number of input items seen by the run.

successCountinteger

Number of items processed successfully.

failureCountinteger

Number of items that failed after retries or validation.

correlationIdstring

Caller-provided or runtime-generated correlation id.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

updatedAtstring date-time

Last update timestamp for this run record.

createdByUserIdstring

Optional user id that initiated or created the run record.

updatedByUserIdstring

Optional user id that last updated the run record.

deletedAtstring date-time

Soft-delete timestamp, if the run record is hidden from normal queries.

Example response

{
  "runId": "9a785884-63ea-4b07-9976-264a1fc595f1",
  "routeId": "1e8ff011-2274-4f16-a7dd-bf0b4fd5262f",
  "connectorInstanceId": "3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5",
  "connectorResourceId": "8d228f50-a86c-4d5f-9eb4-83fdad7d75fa",
  "operationKind": "READ",
  "triggerKind": "ON_DEMAND",
  "status": "PARTIALLY_FAILED",
  "startedAt": "2026-06-18T10:20:00Z",
  "finishedAt": "2026-06-18T10:21:12Z",
  "itemCount": 250,
  "successCount": 247,
  "failureCount": 3,
  "correlationId": "import-2026-06-18-001",
  "metadata": {
    "batch_ref": "vault://imports/license-batches/batch-2026-06-18.csv"
  }
}

Changes

Changed in 1 of the 2 revisions of this API.6410

Jul 17, 202660cb8c70871b6410See the full diff
- ▲
  removed the enum value EXTERNALLY_INITIATED_READ_FROM_VDX of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value EXTERNALLY_INITIATED_WRITE_INTO_VDX of the request property
  request-property-enum-value-removed
- ▲
  added the pattern ^sha256:[0-9a-f]{64}$ to the request property //
  request-property-pattern-added
- ▲
  added the pattern ^sha256:[0-9a-f]{64}$ to the request property //
  request-property-pattern-added
- ▲
  added the pattern ^sha256:[0-9a-f]{64}$ to the request property //
  request-property-pattern-added
- ▲
  added the pattern ^sha256:[0-9a-f]{64}$ to the request property //
  request-property-pattern-added
- ●
  added the new EXTERNALLY_INITIATED_READ enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new EXTERNALLY_INITIATED_WRITE enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new INBOUND enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new OUTBOUND enum value to the response property for the response status
  response-property-enum-value-added
- ○
  added the new EXTERNALLY_INITIATED_READ enum value to the request property
  request-property-enum-value-added
- ○
  added the new EXTERNALLY_INITIATED_WRITE enum value to the request property
  request-property-enum-value-added
- ○
  removed the EXTERNALLY_INITIATED_READ_FROM_VDX enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the EXTERNALLY_INITIATED_WRITE_INTO_VDX enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the INTO_VDX enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the OUT_OF_VDX enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status
  response-property-pattern-added
- ○
  the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status
  response-property-pattern-added
- ○
  the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status
  response-property-pattern-added
- ○
  the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status
  response-property-pattern-added

Full history