---
title: "List recent effects"
method: GET
path: "/v1/effects"
tags: ["Effects"]
---

# List recent effects

`GET /v1/effects`

## Request

- Base URL: `https://ratchetgate.com`
- URL: `https://ratchetgate.com/v1/effects`
- Auth: HTTP bearer

## Query parameters

- `state` 'awaiting_approval' | 'pending' | 'succeeded' | 'failed' | 'indeterminate' | 'denied' | 'cancelled'
- `effect_type` string
- `run_id` string
- `limit` integer

## Response `200`

Default Response

- object
  - `data` object[]
    - `effect_id` string
    - `effect_type` string
    - `idempotency_key` string
    - `state` string
    - `attempt` integer
    - `result` unknown
    - `failure_reason` string, nullable
    - `denial_reason` string, nullable
    - `agent_id` string, nullable
    - `run_id` string, nullable
    - `estimated_cost_micros` integer
    - `actual_cost_micros` integer
    - `lease_expires_at` string, nullable
    - `approval_state` string, nullable
    - `created_at` string
    - `updated_at` string
    - `settled_at` string, nullable

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Insufficient prepaid credit.
- `403`: Scope, policy, or budget refusal.
- `404`: Not found.
- `409`: Conflicting state or idempotency-key reuse.
- `413`: Payload too large.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ratchetgate/apis/ratchet-api.md) · [All operations](https://skmtc.dev/ratchetgate/apis/ratchet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ratchetgate/apis/ratchet-api/revisions/5712f33c692f?raw)