Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Webhooks and events

Where events go, how each delivery went, and the record of every event.

Send Authorization: Bearer vk_test_... on every call. Every route of Webhooks and events.

GET/v1/eventsThe same events as a list you can pull, for anything you missed.

Your API key, scope runtime or all. On the card: events. Every call here is a checked sample.

Request8 fields

Query

limitintegerHow many items per page, 1 to 100. Default 20.
Type
integer
cursorstringWhere to go on from: the next_cursor of the page before, unchanged. Absent: the first page.
Type
string
typestringOnly events of this type.
Type
string
user_idstringOnly this user's, by your id for them.
Type
string
task_idstringOnly this task's (task_...).
Type
string
created_afterstring (date and time)Only events after this ISO 8601 time.
Type
string (date and time)
created_beforestring (date and time)Only events before this ISO 8601 time.
Type
string (date and time)
afterstringOnly events after this one (evt_...), oldest first: poll with the last one you saw and you miss nothing. Without it, newest first.
Type
string
Answers 2002 fields
dataobject[]The items on this page.
idstringThe event (evt_...): the same on every retry, so use it to skip one you already took.
Example
evt_4hq
object"event"Always event.
Type
"event"
typestringAn event a webhook carries: every event of the catalog but the six that ride only the stream (message.delta, task.progress, usage.updated, screen.control, error and ping).
Limits
One of 28 values.
Example
task.completed
mode"live" | "test"The mode it happened in: test or live.
Type
"live" | "test"
created_atstringWhen it happened, as an ISO 8601 time.
Type
string
user_idstring | nullYour id for the user it concerns; null for your company's own Bash, or when it concerns no user.
Type
string | null
task_idstring | nullThe task it concerns (task_...); null when none.
Type
string | null
conversation_idstring | nullThe conversation it concerns (conv_...); null when none.
Type
string | null
datamap of anyWhat it says: its fields depend on its type, as the events reference lists them.
Type
map of any
next_cursorstring | nullSend it as cursor for the next page; null on the last page.
Type
string | null
TypeScript
const events = await vestra.events.list();
Python
events = vestra.events.list()
CLI
vestra events
HTTP
# Stream a conversation live. If the connection drops, reconnect with the last seq you saw.curl -N "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Last-Event-ID: 41" # Read the same events as JSON. You get them in pages, after the seq you give.curl "$VESTRA_BASE_URL/v1/conversations/conv_8f2k/events?format=json&after=41" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Read a task afterwards. You get every step of one task, with tokens and cost per turn.curl "$VESTRA_BASE_URL/v1/tasks/task_91d/trace" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Send events to your server. Register a URL and the events it wants. The signing secret is shown only once.curl "$VESTRA_BASE_URL/v1/webhooks" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "url": "https://hooks.example.com/vestra", "events": ["task.completed", "interaction.created", "usage.cap_reached"] }' # Catch up on what you missed. List the events your webhooks were sent, newest first.curl "$VESTRA_BASE_URL/v1/events?type=task.failed" \  -H "Authorization: Bearer $VESTRA_API_KEY"
MCP
{  "method": "tools/call",  "params": {    "name": "events",    "arguments": { "user": "traveller-42", "conversation": "conv_8f2k", "after": 0 }  }}