Events
Operations tagged Events in the public API.
About Events
An event is the record of one thing that happened on the account — a chatbot created, a dataset trained, an action run failed — with a type from a fixed catalogue (GET /event_types). GET /events is the account's event log: every recorded event, whether or not a webhook endpoint subscribes to it. Sending an event to an endpoint is a separate webhook delivery, one per event and endpoint.
What is recorded. Events are recorded while the account has a consumer — an active API key or an enabled webhook endpoint — so the log starts when the first one exists. An event is written in the same database transaction as the change it describes, and is kept for 90 days by default, then pruned.
Payload. payload is the exact body every delivery of the event POSTs: object, id, type, api_version, created and data.object. data.object is a reference — {object, id} — not the resource; a few types carry more fields (webhook_endpoint.disabled, the billing.* events, ping). Fetch the resource for its current state.
A key restricted to selected agents cannot read events: 403 FORBIDDEN.
IDs you will meet.
id— the event id,evt_and 32 hexadecimal characters, forGET /events/{id}. Receivers dedupe deliveries on it.object_id— the id of what changed, as a string.
IDs on this page
- Event id
<EVENT_ID> - String:
evt_followed by 32 hexadecimal characters. Not an integer:GET /events/1is 404.Get it from
- GET /v1/events returns it as
data[].id - POST /v1/webhook_endpoints/{id}/test returns it as
event_id - GET /v1/webhook_endpoints/{id}/deliveries returns it as
data[].event_id - GET /v1/webhook_deliveries/{id} returns it as
event_id - Every webhook delivery carries it twice: as
idin the JSON body and in theAgentency-Event-Idheader.
- GET /v1/events returns it as
List events
Returns the account's event log, newest first and cursor-paginated: every recorded event, whether or not a webhook endpoint subscribes to it. Use it to catch up after your receiver was down, and
created[gte] / created[lte] to bound the window. Events are kept for 90 days by default.- Required scope
- webhooks:read
- Idempotency
- Read-only
- Rate limits
Query parameters
typestringOptionalOnly events of this exact type, e.g.knowledge.dataset.trained. No wildcard; a type not inGET /event_typesmatches nothing.limitintegerOptionalPage size, clamped to 1–100.Default:
20Minimum:1Maximum:100starting_afterstringOptionalCursor from a previous page'snext_cursor: returns the page after it. A cursor minted for another list,sortororderis 422INVALID_CURSOR.ending_beforestringOptionalCursor from a previous page'sprevious_cursor: returns the page before it. Wins when both cursors are sent.created[gte]stringOptionalOnly rows created on or after this instant:YYYY-MM-DD(whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422INVALID_PARAMETER.created[lte]stringOptionalOnly rows created on or before this instant:YYYY-MM-DD(whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422INVALID_PARAMETER.
Responses
- 200Success.
objectstringRequiredAlways
listdataarray of ApiEventResourceRequiredhas_morebooleanRequirednext_cursorstringnullableRequiredprevious_cursorstringnullableRequiredurlstringRequiredAlways
/v1/events
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDFORBIDDENINSUFFICIENT_SCOPE
- 422Validation failed. See
error.details.Error codesINVALID_CURSORINVALID_PARAMETER
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/events' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "list",
"data": [
{
"object": "event",
"id": "evt_example",
"type": "ping",
"object_type": "ping",
"object_id": null,
"api_version": "2026-08-14",
"payload": {
"id": "evt_example",
"data": {
"object": {
"object": "ping",
"endpoint_id": 1
}
},
"type": "ping",
"object": "event",
"created": 1767225600,
"api_version": "2026-08-14"
},
"created_at": "2026-01-01T00:00:00+00:00"
}
],
"has_more": false,
"next_cursor": null,
"previous_cursor": null,
"url": "/v1/events"
}Retrieve an event
Returns one event, with
payload — the exact body its webhook deliveries POST. Use it to check an event your receiver got, or to fetch one it missed.- Required scope
- webhooks:read
- Idempotency
- Read-only
- Rate limits
Before you call
String:id(path)Event idevt_followed by 32 hexadecimal characters. Not an integer:GET /events/1is 404.Placeholder in the samples:
<EVENT_ID>Get it from
- GET /v1/events returns it as
data[].id - POST /v1/webhook_endpoints/{id}/test returns it as
event_id - GET /v1/webhook_endpoints/{id}/deliveries returns it as
data[].event_id - GET /v1/webhook_deliveries/{id} returns it as
event_id - Every webhook delivery carries it twice: as
idin the JSON body and in theAgentency-Event-Idheader.
- GET /v1/events returns it as
Path parameters
idstringRequiredThe event id (evt_…).
Responses
- 200
ApiEventResourceobjectstringRequiredAlways
eventidstringRequiredThe event id:evt_and 32 hexadecimal characters. The same value aspayload.idand theAgentency-Event-Iddelivery header.typestringRequiredWhat happened, fromGET /event_types.Possible values
chatbot.createdchatbot.updatedchatbot.deletedchatbot.activatedchatbot.deactivatedknowledge.dataset.createdknowledge.dataset.trainedknowledge.dataset.failedknowledge.dataset.deletedcrawl.completedcrawl.failedconversation.startedconversation.message.createdconversation.endedconversation.handoff.requestedcustomer.createdcustomer.updatedlead.capturedaction.run.succeededaction.run.failedchannel.connectedchannel.disconnectedbilling.credits.lowbilling.credits.exhaustedbilling.subscription.updatedbilling.payment.failedbilling.trial.endingapi_key.createdapi_key.revokedwebhook_endpoint.disabledknowledge.collection.createdknowledge.collection.updatedknowledge.collection.deletedfile.createdfile.deletedcrawler.createdcrawler.updatedcrawler.deletedaction.createdaction.updatedaction.deletedcustomer.deletedwidget.updatedplugin.installedplugin.uninstalledprofile.updatedpingaction.form_submittedobject_typestringRequiredThe kind of thing it happened to:payload.data.object.object.Possible values
chatbotknowledge_datasetcrawlconversationmessagecustomerleadaction_runchannelbillingapi_keywebhook_endpointknowledge_collectionfilecrawleractionwidgetpluginprofilepingaction_form_submissionobject_idstringnullableRequiredThe id of the thing it happened to, as a string (an integer id reads"42");nullwhen there is none, as forping.api_versionstringRequiredThe API version that shapedpayload.payloadobjectRequiredThe event exactly as every delivery POSTs it:object,id,type,api_version,created(Unix seconds) anddata.object— a reference such as{"object": "chatbot", "id": 12}, not the resource.created_atstringnullableRequiredWhen the event was recorded (ISO 8601, UTC): the moment of the change.
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDFORBIDDENINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesNOT_FOUND
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/events/<EVENT_ID>' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "event",
"id": "evt_example",
"type": "ping",
"object_type": "ping",
"object_id": null,
"api_version": "2026-08-14",
"payload": {
"id": "evt_example",
"data": {
"object": {
"object": "ping",
"endpoint_id": 1
}
},
"type": "ping",
"object": "event",
"created": 1767225600,
"api_version": "2026-08-14"
},
"created_at": "2026-01-01T00:00:00+00:00"
}List event types
Returns every event type the platform emits, with a one-line description and the resource it is about: the values
enabled_events accepts on a webhook endpoint (besides *), and the catalogue for a subscription picker. ping is only ever sent by POST /webhook_endpoints/{id}/test.- Required scope
- webhooks:read
- Idempotency
- Read-only
- Rate limits
Responses
- 200Success.
objectstringRequiredAlways
listdataarray of objectRequiredEvery event type, grouped by resource.has_morebooleanRequirednext_cursoranynullableRequiredprevious_cursoranynullableRequiredurlstringRequiredAlways
/v1/event_types
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl
curl -X GET 'https://api.agentency.com/v1/event_types' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
json
{
"object": "list",
"data": [
{
"object": "event_type",
"id": "chatbot.created",
"description": "A chatbot was created",
"resource": "chatbot"
},
{
"object": "event_type",
"id": "chatbot.updated",
"description": "A chatbot was updated",
"resource": "chatbot"
},
{
"object": "event_type",
"id": "chatbot.deleted",
"description": "A chatbot was deleted",
"resource": "chatbot"
},
{
"object": "event_type",
"id": "chatbot.activated",
"description": "A chatbot was activated",
"resource": "chatbot"
},
{
"object": "event_type",
"id": "chatbot.deactivated",
"description": "A chatbot was deactivated",
"resource": "chatbot"
},
{
"object": "event_type",
"id": "knowledge.dataset.created",
"description": "A knowledge dataset was created",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.dataset.trained",
"description": "A knowledge dataset finished training",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.dataset.failed",
"description": "A knowledge dataset failed training",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.dataset.deleted",
"description": "A knowledge dataset was deleted",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.collection.created",
"description": "A knowledge collection was created",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.collection.updated",
"description": "A knowledge collection was updated",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "knowledge.collection.deleted",
"description": "A knowledge collection was deleted",
"resource": "knowledge"
},
{
"object": "event_type",
"id": "crawl.completed",
"description": "A crawl completed",
"resource": "crawl"
},
{
"object": "event_type",
"id": "crawl.failed",
"description": "A crawl failed",
"resource": "crawl"
},
{
"object": "event_type",
"id": "conversation.started",
"description": "A conversation started",
"resource": "conversation"
},
{
"object": "event_type",
"id": "conversation.message.created",
"description": "A conversation message was created",
"resource": "conversation"
},
{
"object": "event_type",
"id": "conversation.ended",
"description": "A conversation ended",
"resource": "conversation"
},
{
"object": "event_type",
"id": "conversation.handoff.requested",
"description": "A conversation asked for a human",
"resource": "conversation"
},
{
"object": "event_type",
"id": "customer.created",
"description": "A customer was created",
"resource": "customer"
},
{
"object": "event_type",
"id": "customer.updated",
"description": "A customer was updated",
"resource": "customer"
},
{
"object": "event_type",
"id": "customer.deleted",
"description": "A customer was deleted",
"resource": "customer"
},
{
"object": "event_type",
"id": "lead.captured",
"description": "A lead was captured",
"resource": "lead"
},
{
"object": "event_type",
"id": "action.run.succeeded",
"description": "A Call Action run succeeded",
"resource": "action"
},
{
"object": "event_type",
"id": "action.run.failed",
"description": "A Call Action run failed",
"resource": "action"
},
{
"object": "event_type",
"id": "action.created",
"description": "A Call Action was created",
"resource": "action"
},
{
"object": "event_type",
"id": "action.updated",
"description": "A Call Action was updated",
"resource": "action"
},
{
"object": "event_type",
"id": "action.deleted",
"description": "A Call Action was deleted",
"resource": "action"
},
{
"object": "event_type",
"id": "channel.connected",
"description": "A messaging channel was connected",
"resource": "channel"
},
{
"object": "event_type",
"id": "channel.disconnected",
"description": "A messaging channel was disconnected",
"resource": "channel"
},
{
"object": "event_type",
"id": "billing.credits.low",
"description": "Account credits are low",
"resource": "billing"
},
{
"object": "event_type",
"id": "billing.credits.exhausted",
"description": "Account credits are exhausted",
"resource": "billing"
},
{
"object": "event_type",
"id": "billing.subscription.updated",
"description": "The subscription changed",
"resource": "billing"
},
{
"object": "event_type",
"id": "billing.payment.failed",
"description": "A subscription payment failed",
"resource": "billing"
},
{
"object": "event_type",
"id": "billing.trial.ending",
"description": "The subscription trial is about to end",
"resource": "billing"
},
{
"object": "event_type",
"id": "api_key.created",
"description": "An API key was created",
"resource": "api_key"
},
{
"object": "event_type",
"id": "api_key.revoked",
"description": "An API key was revoked",
"resource": "api_key"
},
{
"object": "event_type",
"id": "webhook_endpoint.disabled",
"description": "A webhook endpoint was auto-disabled",
"resource": "webhook_endpoint"
},
{
"object": "event_type",
"id": "file.created",
"description": "A file was uploaded",
"resource": "file"
},
{
"object": "event_type",
"id": "file.deleted",
"description": "A file was deleted",
"resource": "file"
},
{
"object": "event_type",
"id": "crawler.created",
"description": "A crawler was created",
"resource": "crawler"
},
{
"object": "event_type",
"id": "crawler.updated",
"description": "A crawler was updated",
"resource": "crawler"
},
{
"object": "event_type",
"id": "crawler.deleted",
"description": "A crawler was deleted",
"resource": "crawler"
},
{
"object": "event_type",
"id": "widget.updated",
"description": "Widget settings were updated",
"resource": "widget"
},
{
"object": "event_type",
"id": "plugin.installed",
"description": "A website plugin was installed",
"resource": "plugin"
},
{
"object": "event_type",
"id": "plugin.uninstalled",
"description": "A website plugin was uninstalled",
"resource": "plugin"
},
{
"object": "event_type",
"id": "profile.updated",
"description": "The account profile was updated",
"resource": "profile"
},
{
"object": "event_type",
"id": "ping",
"description": "A test ping from Agentency",
"resource": "ping"
}
],
"has_more": false,
"next_cursor": null,
"previous_cursor": null,
"url": "/v1/event_types"
}