Source: https://docs.cumuluslabs.io/reference/runs.effects
Content version: b9b5057a

# runs.effects

Read the run's governed effects and receipts

## Request {#request}

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

- MCP: `runs_effects`
- SDK: `client.runs.effects` (SDK path arguments use `path`; MCP uses `params`).
- Minimum API key role: **viewer**.
- Idempotency: **none**.

Use the request schema below. Read IDs from earlier operation results.

## Input schema {#input-schema}

```json
{
  "parameters": [
    {
      "name": "run_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": null
}
```

## Responses {#responses}

```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 {#schemas}

```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"
          },
          "run_id": {
            "type": "string",
            "format": "uuid"
          },
          "attempt_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "effect_key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "action": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "version": {
                "type": "integer",
                "exclusiveMinimum": true,
                "minimum": 0
              }
            },
            "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": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "nullable": true
          },
          "ordinal": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "intended",
              "sending",
              "succeeded",
              "failed",
              "uncertain"
            ]
          },
          "decision": {
            "type": "object",
            "properties": {
              "decision": {
                "type": "string",
                "enum": [
                  "allow",
                  "deny",
                  "unavailable"
                ]
              },
              "reason": {
                "type": "string",
                "nullable": true
              },
              "policy_version": {
                "type": "string"
              }
            },
            "required": [
              "decision",
              "reason",
              "policy_version"
            ],
            "additionalProperties": false,
            "nullable": true
          },
          "send_attempts": {
            "type": "integer",
            "minimum": 0
          },
          "receipts": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "http"
                      ]
                    },
                    "status": {
                      "type": "integer"
                    },
                    "response_sha256": {
                      "allOf": [
                        {
                          "type": "string",
                          "pattern": "^[a-f0-9]{64}$"
                        }
                      ],
                      "nullable": true
                    },
                    "response_bytes": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "duration_ms": {
                      "type": "integer"
                    },
                    "send_attempt": {
                      "type": "integer",
                      "exclusiveMinimum": true,
                      "minimum": 0
                    }
                  },
                  "required": [
                    "kind",
                    "status",
                    "response_sha256",
                    "response_bytes",
                    "duration_ms",
                    "send_attempt"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "sip_transfer"
                      ]
                    },
                    "refer_status": {
                      "type": "integer",
                      "nullable": true
                    },
                    "final_sip_status": {
                      "type": "integer",
                      "nullable": true
                    },
                    "disconnect_reason": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "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": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "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"
                    },
                    "measurement_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    }
                  },
                  "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": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "settled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "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 {#errors}

See [API error handling](https://docs.cumuluslabs.io/api#errors) and [Troubleshooting](https://docs.cumuluslabs.io/troubleshooting).

## Related guides {#related-guides}

- [Using the API](https://docs.cumuluslabs.io/api)
- [Runs](https://docs.cumuluslabs.io/runs)
- [Troubleshooting](https://docs.cumuluslabs.io/troubleshooting)