SPsphereon-opensource
Runs

Get a connector run

Changed on

Reads one connector execution record, including status, timestamps, counts, correlation id, and error summary. Detailed logs are exposed as run events.

get/runs/{runId}

Request

Path parameters

runIdstring uuid required

Stable identifier for a connector route or operation run.

Example:9a785884-63ea-4b07-9976-264a1fc595f1

Stable identifier of a connector route or operation execution.

Response

Connector run.

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.

exchangeMode'PLATFORM_INITIATED_PULL' | 'PLATFORM_INITIATED_PUSH' | 'EXTERNALLY_INITIATED_READ' | 'EXTERNALLY_INITIATED_WRITE' | 'SUBSCRIPTION_CALLBACK' | 'BIDIRECTIONAL_SYNC'

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.

operationKind'READ' | 'WRITE' | 'UPDATE' | 'DELETE' | 'UPSERT' | 'QUERY' | 'SEARCH' | 'IMPORT' | 'EXPORT' | 'INVOKE' | 'DISCOVER' | 'VALIDATE'

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

triggerKind'INLINE' | 'ON_DEMAND' | 'SCHEDULED' | 'EVENT' | 'WEBHOOK' | 'PIPELINE'

Mechanism that initiated the run.

status'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'PARTIALLY_FAILED' | 'CANCELLED' required

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

  • 60cb8c70871bRevision changes
    • warning

      added the new EXTERNALLY_INITIATED_READ enum value to the response property for the response status

    • warning

      added the new EXTERNALLY_INITIATED_WRITE enum value to the response property for the response status

    • warning

      added the new INBOUND enum value to the response property for the response status

    • warning

      added the new OUTBOUND enum value to the response property for the response status

    • info

      removed the EXTERNALLY_INITIATED_READ_FROM_VDX enum value from the response property for the response status

    • info

      removed the EXTERNALLY_INITIATED_WRITE_INTO_VDX enum value from the response property for the response status

    • info

      removed the INTO_VDX enum value from the response property for the response status

    • info

      removed the OUT_OF_VDX enum value from the response property for the response status

    • info

      the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status

    • info

      the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status

    • info

      the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status

    • info

      the // response's property pattern ^sha256:[0-9a-f]{64}$ was added for the status