Skip to content
Home/
REST API Reference
/
/
Fin Agent Status Updated...

Fin Agent Status Updated Event

Event fired when Fin's status changes during a conversation. Fin will report its status to the client via this event.

event_namestringrequired

The name of the event.

Value:"fin_status_updated"
Example:"fin_status_updated"
conversation_idstringrequired

The ID of the conversation.

Example:"123456"
user_idstringrequired

The ID of the user.

Example:"7891"
statusstringrequired

Fin's current status.

  • thinking: Fin has started running a procedure. Not sent on every turn
  • awaiting_user_reply: Fin has finished replying and is waiting for the user to respond
  • escalated: The conversation has been escalated to a human
  • resolved: The user's query has been resolved
  • complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow
Enum:"thinking""awaiting_user_reply""escalated""resolved""complete"
Example:"escalated"
reasonstring

Optional. A human-readable explanation of why the conversation was escalated. Only present when status is 'escalated'.

When you escalate deterministically with /fin/escalate, the reason is always "Escalation requested via API".

The following reasons apply to Fin-decided escalations when Fin owns the conversation (/fin/start, /fin/procedures/{procedure_id}/run, and /fin/reply on a conversation that was started that way). /fin/ask can report any of them, because escalation rules still apply and the conversation can still be routed to a team or finish without resolution. On an Ask, "Escalation requested by user" normally only follows an escalation rule match.

  • "Escalation requested by user"
  • "Escalation rule: {rule_name}"
  • "Escalation rule matched"
  • "Routed to team"
  • "Conversation finished without resolution"

"Escalation requested by user" is sent whenever Fin decides to hand over, not only when the user asks for a human, for example on a procedure handoff or a custom answer handover. It also follows an escalation rule match, as a second escalated event after the rule's reason. While a procedure is running, every escalation Fin decides on reports it.

Example:"Escalation requested via API"
created_at_msstring, (date-time)required

The timestamp the event was created at, with millisecond precision.

Example:"2025-01-24T10:00:00.123Z"
{
  "event_name": "fin_status_updated",
  "conversation_id": "123456",
  "user_id": "7891",
  "status": "escalated",
  "reason": "Escalation requested via API",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}