---
title: "List connector runs"
method: GET
path: "/runs"
tags: ["Runs"]
---

# List connector runs

`GET /runs`

Lists route and operation runs across the tenant. Use this direct tenant-wide run resource
for operational dashboards, customer support, audit trails, retry decisions, and monitoring
failed or partially failed imports and exports. Use `/routes/{routeId}/runs` for
route-scoped history.

## Query parameters

- `status` 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'PARTIALLY_FAILED' | 'CANCELLED' — Execution status of a route run or connector operation run.
- `routeId` string, uuid — Stable identifier for a connector route.
- `connectorInstanceId` string, uuid — Stable platform identifier for a configured connector instance.
- `invocationBindingId` string — Stable identifier of the domain invocation binding that caused a connector call.
- `logicalConnectionBindingId` string — Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.
- `physicalConnectorInstanceId` string, 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.
- `protocolSurface` 'OID4VCI' | 'OID4VP' | 'FORM' | 'PORTAL' | 'WORKFLOW' | 'APPLICATION' — Product, protocol, form, portal, workflow, or application surface that owns a connector invocation binding.
- `correlationId` string
- `page` integer
- `size` integer

## Response `200`

Paged connector runs.

- ConnectorRunPage — Page of connector runs.
  - `data` ConnectorRun[], required
    - `runId` string, uuid, required — Stable identifier for a connector route or operation run.
    - `routeId` string, uuid — Stable identifier for a connector route.
    - `bindingId` string, uuid — Stable identifier for a connector operation binding.
    - `connectorInstanceId` string, uuid — Stable platform identifier for a configured connector instance.
    - `invocationBindingId` string — Stable identifier of the domain invocation binding that caused a connector call.
    - `logicalConnectionBindingId` string — Stable identifier of a tenant, OU, brand, legal-entity, or channel usage binding for a physical connector instance.
    - `physicalConnectorInstanceId` string, 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.
    - `governance` ConnectorGovernanceEnvelope — Governance metadata attached to connector records, invocations, and runs before data crosses a protocol, form, vault, dataspace, or external-exchange boundary.
      - `classification` string
      - `sensitivity` string
      - `specialCategory` boolean
      - `legalBasis` string
      - `purpose` string
      - `b2bUsagePurpose` string — B2B or dataspace usage purpose, separate from privacy legal basis and processing purpose.
      - `frameworkAgreementRef` string
      - `contractReference` string
      - `minimizationStatus` 'NOT_EVALUATED' | 'MINIMIZED' | 'REDACTED' | 'FULL_DATASET' | 'EXCESSIVE'
      - `retentionProfileId` string
      - `retention` RetentionSpec — Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
        - `purpose` string — Processing purpose.
        - `legalBasis` string — Legal or contractual basis for retention.
        - `retentionPeriod` string — ISO-8601 duration, for example P30D or P7Y.
        - `deleteAction` 'DELETE' | 'ANONYMIZE' | 'PSEUDONYMIZE' | 'TOMBSTONE' | 'REVIEW' — Action to apply when retention expires or deletion is required by policy.
        - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
      - `crossBorderRestriction` 'NONE' | 'SAME_COUNTRY' | 'EEA_ONLY' | 'APPROVED_COUNTRIES' | 'CONTRACT_REQUIRED' | 'BLOCKED'
      - `encryptionRequirement` 'NONE' | 'IN_TRANSIT' | 'AT_REST' | 'AT_REST_AND_IN_TRANSIT' | 'CUSTOMER_MANAGED_KEY'
      - `dpiaRequired` boolean
      - `integrity` ConnectorIntegrityReference — Integrity and evidence references carried with governed connector ingress, egress, and run lineage.
        - `originalPayloadHash` string
        - `canonicalPayloadHash` string
        - `transformationHash` string
        - `evidenceRef` string
        - `vaultRef` string
        - `signatureRef` string
        - `sealRef` string
        - `timestampRef` string
        - `sourceAuthenticityVerdict` string
        - `outputManifestHash` string
      - `policyDecisionId` string
      - `relianceVerdict` 'NOT_EVALUATED' | 'RELIABLE' | 'CONDITIONAL' | 'NOT_RELIABLE'
      - `auditCategory` 'PROTOCOL_ISSUANCE' | 'PROTOCOL_VERIFICATION' | 'FORM' | 'PORTAL' | 'WORKFLOW' | 'DATASPACE' | 'INDUSTRIAL' | 'EXTERNAL_EXCHANGE' | 'VAULT' | 'SYSTEM_CATALOG'
    - `partyAnchors` ConnectorPartyAnchorSet — Party, relationship, and projection candidates attached to connector invocation/run lineage.
      - `anchors` ConnectorPartyAnchor[]
        - `role` string
        - `party` PartyRef — Neutral Party reference carried by EDK connector envelopes without importing the VDX Party repository.
          - `partyId` string
          - `externalId` string
          - `partyType` string
          - `displayName` string
          - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
        - `relationships` object[]
      - `relationshipCandidates` object[]
      - `projectionCandidates` object[]
    - `protocolContext` ConnectorProtocolEventContext — Canonical protocol, form, portal, or workflow event context mapped into connector run lineage.
      - `tenantId` string
      - `organizationUnitId` string
      - `brandId` string
      - `legalEntityId` string
      - `actor` PartyRef — Neutral Party reference carried by EDK connector envelopes without importing the VDX Party repository.
        - `partyId` string
        - `externalId` string
        - `partyType` string
        - `displayName` string
        - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
      - `protocolSurface` 'OID4VCI' | 'OID4VP' | 'FORM' | 'PORTAL' | 'WORKFLOW' | 'APPLICATION'
      - `ownerReference` string
      - `stage` string
      - `sessionId` string
      - `transactionId` string
      - `correlationId` string
    - `connectorResourceId` string, 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.
    - `startedAt` string, date-time, required — Timestamp when execution started.
    - `finishedAt` string, date-time — Timestamp when execution finished, if complete.
    - `itemCount` integer — Number of input items seen by the run.
    - `successCount` integer — Number of items processed successfully.
    - `failureCount` integer — Number of items that failed after retries or validation.
    - `correlationId` string — Caller-provided or runtime-generated correlation id.
    - `error` ApiError — Stable, machine-readable error body content.
      - `code` string, required — Stable, machine-readable error category.
      - `message` string, required — Human-readable error message.
      - `details` object — Additional error context or field-level details.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `updatedAt` string, date-time — Last update timestamp for this run record.
    - `createdByUserId` string — Optional user id that initiated or created the run record.
    - `updatedByUserId` string — Optional user id that last updated the run record.
    - `deletedAt` string, date-time — Soft-delete timestamp, if the run record is hidden from normal queries.
  - `pagination` Page, required — Pagination metadata emitted with each paged response under the `pagination` property.
    - `limit` integer, required — Maximum number of records requested for this page.
    - `offset` integer, required — Zero-based offset of the first record in this page.
    - `page` integer, required — Zero-based page index derived from offset and limit.
    - `size` integer, required — Effective page size.
    - `total` integer, required — Total number of matching records.
    - `totalPages` integer, required — Total number of available pages.
    - `hasMore` boolean, required — Whether another page is available after this page.

## Other responses

- `400` — Validation error.
- `401` — Authentication is required.

---

[API](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/connector-integration-profile-api/revisions/60cb8c70871b/schema)