CumulusDocs
Open Studio
On this page

Get action receipts

Read the run’s action decisions, send attempts and receipts. Check these records when an external action fails or its outcome is uncertain.

Operation ID: runs.effects.

Request

GET /api/v1/runs/{run_id}/effects

  • TypeScript SDK: client.runs.effects (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "runs.effects" (path arguments use input.path). Legacy alias: runs_effects. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: viewer.
  • Idempotency: No idempotency header required.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Set each path variable to an ID returned by an earlier API request.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS "${CUMULUS_BASE_URL%/}/api/v1/runs/${RUN_ID}/effects" \
  -H "Authorization: Bearer $CUMULUS_API_KEY"

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const response = await client.runs.effects({
  "path": {
    "run_id": "<run_id>"
  }
});

Input schema

Path, query and header parameters

run_id

path parameter · Required.

Type: string (uuid). pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.

JSON request body

This operation has no JSON request body.

Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "run_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
      }
    }
  ],
  "requestBody": null
}

Responses

HTTP 200

Read the run's governed effects and receipts

application/json

FieldType or valuesRequiredDescription and limits
itemsarray of objectRequired—
items[].effect_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
items[].run_idstring (uuid)RequiredRun identifier returned when the run was admitted. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
items[].attempt_idstring (uuid) or nullRequiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
items[].effect_keystringRequiredminLength: 1. maxLength: 256.
items[].actionobjectRequired—
items[].action.idstringRequired—
items[].action.versionintegerRequiredGreater than 0. At most 9007199254740991.
items[].effect_kind"none" · "transaction" · "gateway_inference" · "http" · "livekit" · "sip_dial" · "sip_transfer" · "sip_hangup" · "run_admission" · "gpu"Required—
items[].node_idstring or nullRequiredminLength: 1. maxLength: 128.
items[].ordinalinteger or nullRequiredAt least 0. At most 9007199254740991.
items[].state"intended" · "sending" · "succeeded" · "failed" · "uncertain"Required—
items[].decisionobject or nullRequired—
items[].decision.decision"allow" · "deny" · "unavailable"Required in a non-null parent—
items[].decision.reasonstring or nullRequired in a non-null parent—
items[].decision.policy_versionstringRequired in a non-null parent—
items[].send_attemptsintegerRequiredAt least 0. At most 9007199254740991.
items[].receiptsarray of objectRequired—
items[].receipts[] · variant 1object—Fields for this schema branch.
items[].receipts[].kind"http"Required—
items[].receipts[].statusintegerRequiredAt least -9007199254740991. At most 9007199254740991.
items[].receipts[].response_sha256string or nullRequiredpattern: ^[a-f0-9]{64}$.
items[].receipts[].response_bytesintegerRequiredAt least 0. At most 9007199254740991.
items[].receipts[].duration_msintegerRequiredAt least -9007199254740991. At most 9007199254740991.
items[].receipts[].send_attemptintegerRequiredGreater than 0. At most 9007199254740991.
items[].receipts[] · variant 2object—Fields for this schema branch.
items[].receipts[].kind"sip_transfer"Required—
items[].receipts[].refer_statusinteger or nullRequiredAt least -9007199254740991. At most 9007199254740991.
items[].receipts[].final_sip_statusinteger or nullRequiredAt least -9007199254740991. At most 9007199254740991.
items[].receipts[].disconnect_reasonstring or nullRequired—
items[].receipts[] · variant 3object—Fields for this schema branch.
items[].receipts[].kind"sip_dial"Required—
items[].receipts[].participant_idstringRequired—
items[].receipts[].sip_call_idstring or nullRequired—
items[].receipts[] · variant 4object—Fields for this schema branch.
items[].receipts[].kind"livekit"Required—
items[].receipts[].resource_idstringRequired—
items[].receipts[] · variant 5object—Fields for this schema branch.
items[].receipts[].kind"gateway_inference"Required—
items[].receipts[].attempt_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
items[].receipts[].measurement_idstring (uuid) or nullRequiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
items[].receipts[] · variant 6object—Fields for this schema branch.
items[].receipts[].kind"transaction"Required—
items[].receipts[].tablestringRequired—
items[].receipts[].row_idstringRequired—
items[].error_codestring or nullRequired—
items[].created_atstring (date-time)Requiredpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
items[].settled_atstring (date-time) or nullRequiredpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "200": {
    "description": "Read the run's governed effects and receipts",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RunsEffectsResponse200"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "RunsEffectsResponse200": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EffectRecord"
            }
          }
        },
        "required": [
          "items"
        ],
        "additionalProperties": false
      },
      "EffectRecord": {
        "type": "object",
        "properties": {
          "effect_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          },
          "run_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          },
          "attempt_id": {
            "nullable": true,
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          },
          "effect_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "action": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "version": {
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "id",
              "version"
            ],
            "additionalProperties": false
          },
          "effect_kind": {
            "type": "string",
            "enum": [
              "none",
              "transaction",
              "gateway_inference",
              "http",
              "livekit",
              "sip_dial",
              "sip_transfer",
              "sip_hangup",
              "run_admission",
              "gpu"
            ]
          },
          "node_id": {
            "nullable": true,
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "ordinal": {
            "nullable": true,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "state": {
            "type": "string",
            "enum": [
              "intended",
              "sending",
              "succeeded",
              "failed",
              "uncertain"
            ]
          },
          "decision": {
            "nullable": true,
            "type": "object",
            "properties": {
              "decision": {
                "type": "string",
                "enum": [
                  "allow",
                  "deny",
                  "unavailable"
                ]
              },
              "reason": {
                "nullable": true,
                "type": "string"
              },
              "policy_version": {
                "type": "string"
              }
            },
            "required": [
              "decision",
              "reason",
              "policy_version"
            ],
            "additionalProperties": false
          },
          "send_attempts": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "receipts": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "http"
                      ]
                    },
                    "status": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "response_sha256": {
                      "nullable": true,
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "response_bytes": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "duration_ms": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "send_attempt": {
                      "type": "integer",
                      "minimum": 0,
                      "exclusiveMinimum": true,
                      "maximum": 9007199254740991
                    }
                  },
                  "required": [
                    "kind",
                    "status",
                    "response_sha256",
                    "response_bytes",
                    "duration_ms",
                    "send_attempt"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "sip_transfer"
                      ]
                    },
                    "refer_status": {
                      "nullable": true,
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "final_sip_status": {
                      "nullable": true,
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "disconnect_reason": {
                      "nullable": true,
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "refer_status",
                    "final_sip_status",
                    "disconnect_reason"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "sip_dial"
                      ]
                    },
                    "participant_id": {
                      "type": "string"
                    },
                    "sip_call_id": {
                      "nullable": true,
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "participant_id",
                    "sip_call_id"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "livekit"
                      ]
                    },
                    "resource_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "resource_id"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "gateway_inference"
                      ]
                    },
                    "attempt_id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
                    },
                    "measurement_id": {
                      "nullable": true,
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
                    }
                  },
                  "required": [
                    "kind",
                    "attempt_id",
                    "measurement_id"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "transaction"
                      ]
                    },
                    "table": {
                      "type": "string"
                    },
                    "row_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "table",
                    "row_id"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "error_code": {
            "nullable": true,
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          },
          "settled_at": {
            "nullable": true,
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          }
        },
        "required": [
          "effect_id",
          "run_id",
          "attempt_id",
          "effect_key",
          "action",
          "effect_kind",
          "node_id",
          "ordinal",
          "state",
          "decision",
          "send_attempts",
          "receipts",
          "error_code",
          "created_at",
          "settled_at"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version b2bf3e0cCustomer SDKMarkdown source
Get action receipts · Cumulus developer docs