Skip to main content
Guppy is event‑driven. All state changes are emitted as events. We recommend setting up webhooks to stay in sync with intent progress.

​
Debugging / Polling (v1)

During the v1 migration phase, Guppy also exposes an events timeline endpoint to fetch recorded events for a specific intent (useful for debugging and dashboards): GET /intents/{intent_id}/events Query params:
  • limit (default 50, max 200)
  • cursor (optional; use the returned next_cursor)
Response: 
{
  "request_id": "req_...",
  "intent_id": "int_...",
  "events": [
    {
      "event_id": "evt_...",
      "type": "intent.created",
      "timestamp": "2026-01-18T21:10:00Z",
      "data": {}
    }
  ],
  "next_cursor": null
}

​
Event Types

  • intent.created: Intent has been successfully recorded.
  • intent.waiting: Conditions are not yet met (e.g., out of stock).
  • intent.executing: Guppy has started the execution flow.
  • execution.step_started: A specific action in the plan has started.
  • execution.step_failed: A step failed but may be retried.
  • execution.needs_user_action: Input (3DS, OTP) is required to proceed.
  • intent.succeeded: Intent goal has been achieved.
  • intent.failed: Intent has reached a terminal failure state.

​
Event Payload

{
  "event_id": "evt_123",
  "type": "intent.succeeded",
  "intent_id": "int_789",
  "timestamp": "2026-01-12T02:14:55Z",
  "data": {
    "merchant": "target",
    "total_charged_cents": 79999,
    "currency": "USD"
  }
}