Enterprise Knowledge observability

With Enterprise Knowledge observability, you can monitor, debug, and trace product events across the entire lifecycle of knowledge bases and knowledge sources. This includes tracking create, read, update, and delete (CRUD) operations, as well as search, indexing, and retrieval operations.

Capabilities

Feature	Description	Primary use case
Product event logging	Structured logs for lifecycle operations (create, read, update, delete, search, and indexing) across Enterprise Knowledge resources	Auditing, event tracing, and downstream analysis
Error and warning logs	Detailed diagnostics for all CRUD operation failures, including `error_code`, `display_message`, possible causes, and suggested actions	Accelerated root cause analysis and debugging
Alerting	Set custom error and warning thresholds in the Twilio Console and route proactive alerts across multiple channels, including email, webhooks, and PagerDuty	Proactive incident response and SRE workflows
Traceability and lineage	Trace ID propagation across Conversation Orchestrator, Conversation Intelligence, and Knowledge, including the `requestId` and `correlationId` fields documented in Log entry schema	End-to-end debugging and correlation across the Twilio AI stack
Onboarding UI errors	Built-in observability for errors encountered during setup (for example, profile and knowledge ingest, or identity resolution). Errors are tagged with `interface_type: "UI"` in logs	Debugging setup and configuration failures
Data export and integration	Real-time log export using Twilio Event Streams to external systems, such as a SIEM (Security Information and Event Management), a data warehouse, or an analytics platform, with personal data redaction	Agent monitoring, compliance, and custom analytics

Access logs

To view Enterprise Knowledge logs:

Open the Twilio Console.
Go to Monitor > Debugger.
Filter by event type (for example, com.twilio.knowledge.knowledge.created) or search for knowledge-related events.
To view error descriptions, possible causes, and suggested remediation steps, select any log entry to expand its full diagnostic panel.

Product event logs

Enterprise Knowledge emits a structured log event for each significant state change. Events follow the naming convention:

com.twilio.<DOMAIN>.<RESOURCE>.<ACTION>

Knowledge events

Event type	Description	Log levels
`com.twilio.knowledge.knowledge.created`	A new knowledge document or source is registered, before content is processed	`INFO`, `ERROR`
`com.twilio.knowledge.knowledge.searched`	A knowledge search operation completed	`INFO`, `ERROR`
`com.twilio.knowledge.knowledge.updated`	An existing knowledge document or source is modified, including source refreshes	`INFO`, `ERROR`, `WARNING`
`com.twilio.knowledge.knowledge.deleted`	A knowledge document or source is permanently removed	`INFO`, `ERROR`
`com.twilio.knowledge.knowledge.indexed`	A knowledge source finishes processing and is indexed for retrieval	`INFO`, `ERROR`, `WARNING`

Knowledge base events

Event type	Description	Log levels
`com.twilio.knowledge.knowledgebase.created`	A new knowledge base is provisioned	`INFO`, `ERROR`
`com.twilio.knowledge.knowledgebase.updated`	The knowledge base configuration is modified	`INFO`, `ERROR`, `WARNING`
`com.twilio.knowledge.knowledgebase.deleted`	The knowledge base is removed	`INFO`, `ERROR`

(information)

Info

Field-by-field payload schemas for individual knowledge base events aren't included in this guide. Each event's body follows the same top-level structure described in Log entry schema, and at minimum includes created_by, interface_type, latency_ms, and knowledge_base_id, as shown in the example log entry.

Deprecated event names

Enterprise Knowledge previously emitted the following event names, which might still appear in logs generated before this update:

Deprecated event	Replacement
`com.twilio.knowledge.searched`	`com.twilio.knowledge.knowledge.searched`
`com.twilio.knowledge.uploaded.text`	`com.twilio.knowledge.knowledge.indexed` (with `source_type: "text"`)
`com.twilio.knowledge.uploaded.url`	`com.twilio.knowledge.knowledge.indexed` (with `source_type: "web"`)

Knowledge event payloads

Each knowledge.* event's body contains fields specific to that event type. The following sections describe the payload for each event and show representative log entries.

The `com.twilio.knowledge.knowledge.created` event

This event is fired when a new knowledge document or source is registered. The exact fields present depend on source_type:

Field	Type	Description
`knowledge_base_id`	string	ID of the parent knowledge base
`knowledge_id`	string	ID of the knowledge resource
`created_by`	string	User SID or service identity that initiated the request
`description`	string	Description provided for the knowledge resource
`source_type`	string	`text`, `web`, or `file`
`interface_type`	string	`UI` or `API`
`latency_ms`	integer	Processing time in milliseconds
`error_code`	string	The error code for the failure, from Error and warning logs; `null` on success
`display_message`	string	A human-readable description of the error; `null` on success
`content_snippet`	string	The first 10 characters of the submitted text (text uploads only)
`content_size`	integer	Size in bytes (text uploads only)
`content_char_count`	integer	Character count (text uploads only)
`source_url`	string	The crawled source URL (web uploads only)
`page_depth`	integer	Crawl depth (web uploads only)
`file_name`	string	Uploaded file name (file uploads only)
`raw_text_size`	integer	Total file size in bytes (file uploads only)

For example, Enterprise Knowledge logs an INFO event for a successful text-source creation:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "created_by": "US12345678901234567890123456789012",
5  "description": "Product documentation",
6  "source_type": "text",
7  "interface_type": "UI",
8  "latency_ms": 1234,
9  "error_code": null,
10  "display_message": null,
11  "content_snippet": "Product do",
12  "content_size": 5120,
13  "content_char_count": 5000
14}

If creation fails, error_code and display_message are populated and knowledge_id is null:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": null,
4  "created_by": "US12345678901234567890123456789012",
5  "description": "Failed creation",
6  "source_type": "text",
7  "interface_type": "API",
8  "latency_ms": 5234,
9  "error_code": "420001",
10  "display_message": "Knowledge could not be created."
11}

The `com.twilio.knowledge.knowledge.searched` event

This event is fired when a search query runs against a knowledge base:

Field	Type	Description
`knowledge_base_id`	string	ID of the knowledge base searched
`search_query`	string	The first 10 characters of the search query text
`result_count`	integer	Number of results returned
`searched_by`	string	User SID or service identity that ran the search
`knowledge_searched`	array	List of `{knowledge_ids, confidence_score}` objects for the top results
`interface_type`	string	`UI` or `API`
`latency_ms`	integer	Processing time in milliseconds
`error_code`	string	The error code for the failure, from Error and warning logs; `null` on success
`display_message`	string	A human-readable description of the error; `null` on success

For example, Enterprise Knowledge logs an INFO event for a successful search:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "search_query": "how to res",
4  "result_count": 2,
5  "searched_by": "US12345678901234567890123456789012",
6  "knowledge_searched": [
7    { "knowledge_ids": "know_knowledge_00000000000000000000000000", "confidence_score": 0.92 },
8    { "knowledge_ids": "know_knowledge_00000000000000000000000001", "confidence_score": 0.87 }
9  ],
10  "interface_type": "UI",
11  "latency_ms": 145,
12  "error_code": null,
13  "display_message": null
14}

If the search fails, result_count is 0 and knowledge_searched is empty:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "search_query": "invalid qu",
4  "result_count": 0,
5  "searched_by": "US12345678901234567890123456789012",
6  "knowledge_searched": [],
7  "interface_type": "API",
8  "latency_ms": 3000,
9  "error_code": "420003",
10  "display_message": "Search query failed."
11}

The `com.twilio.knowledge.knowledge.updated` event

This event is fired when a knowledge resource's metadata or content is modified, including source refreshes:

Field	Type	Description
`knowledge_base_id`	string	ID of the parent knowledge base
`knowledge_id`	string	ID of the knowledge resource
`updated_by`	string	User SID or service identity that made the update
`updated_fields`	array	List of field names that were updated, such as `name`, `description`, or `source`
`refreshed`	boolean	Whether the update was a refresh from the original source
`interface_type`	string	`UI` or `API`
`latency_ms`	integer	Processing time in milliseconds
`error_code`	string	The error code for the failure or partial success, from Error and warning logs; `null` on success
`display_message`	string	A human-readable description of the error or partial-success condition; `null` on success

For example, Enterprise Knowledge logs an INFO event for a successful update:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "updated_by": "US12345678901234567890123456789012",
5  "updated_fields": ["name", "description"],
6  "refreshed": false,
7  "interface_type": "UI",
8  "latency_ms": 456,
9  "error_code": null,
10  "display_message": null
11}

If only some fields update successfully, Enterprise Knowledge logs a WARNING event:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "updated_by": "US12345678901234567890123456789012",
5  "updated_fields": ["name"],
6  "refreshed": false,
7  "interface_type": "API",
8  "latency_ms": 567,
9  "error_code": "420009",
10  "display_message": "Partial update, content skipped."
11}

If the update fails entirely, updated_fields is empty:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "updated_by": "US12345678901234567890123456789012",
5  "updated_fields": [],
6  "refreshed": false,
7  "interface_type": "UI",
8  "latency_ms": 2340,
9  "error_code": "420010",
10  "display_message": "Knowledge resource update failed."
11}

The `com.twilio.knowledge.knowledge.deleted` event

This event is fired when a knowledge resource is permanently removed:

Field	Type	Description
`knowledge_base_id`	string	ID of the parent knowledge base
`knowledge_id`	string	ID of the deleted knowledge resource
`deleted_by`	string	User SID or service identity that requested the deletion
`interface_type`	string	`UI` or `API`
`latency_ms`	integer	Processing time in milliseconds
`error_code`	string	The error code for the failure, from Error and warning logs; `null` on success
`display_message`	string	A human-readable description of the error; `null` on success

For example, Enterprise Knowledge logs an INFO event for a successful deletion:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "deleted_by": "US12345678901234567890123456789012",
5  "interface_type": "UI",
6  "latency_ms": 345,
7  "error_code": null,
8  "display_message": null
9}

If the deletion fails, error_code and display_message are populated:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "deleted_by": "US12345678901234567890123456789012",
5  "interface_type": "UI",
6  "latency_ms": 890,
7  "error_code": "420011",
8  "display_message": "Knowledge resource deletion failed."
9}

The `com.twilio.knowledge.knowledge.indexed` event

This event is fired when a knowledge source finishes processing and becomes searchable. This event shares its knowledge_id with the corresponding created event for the same source:

Field	Type	Description
`knowledge_base_id`	string	ID of the parent knowledge base
`knowledge_id`	string	ID of the knowledge resource
`created_by`	string	User SID or service identity that submitted the source
`latency_ms`	integer	Processing time in milliseconds
`error_code`	string	The error code for the failure or partial success, from Error and warning logs; `null` on success
`display_message`	string	A human-readable description of the error or partial-success condition; `null` on success
`page_count`	integer	Number of pages crawled (web sources only)

For example, Enterprise Knowledge logs an INFO event when a web source indexes successfully:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000000",
4  "created_by": "US12345678901234567890123456789012",
5  "latency_ms": 1234,
6  "error_code": null,
7  "display_message": null,
8  "page_count": 45
9}

If a web source only partially indexes, Enterprise Knowledge logs a WARNING event:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": "know_knowledge_00000000000000000000000002",
4  "created_by": "US12345678901234567890123456789012",
5  "latency_ms": 8900,
6  "error_code": "420007",
7  "display_message": "URL crawl partially timed out.",
8  "page_count": 45
9}

If a web source fails to index, knowledge_id is null:

1{
2  "knowledge_base_id": "know_knowledgebase_00000000000000000000000000",
3  "knowledge_id": null,
4  "created_by": "US98765432109876543210987654321098",
5  "latency_ms": 5234,
6  "error_code": "420006",
7  "display_message": "Failed to crawl or fetch the URL."
8}

Log entry schema

Every log entry shares a common top-level structure. Top-level field names use camelCase (for example, errorCode). Fields inside body use snake_case (for example, error_code).

Field	Type	Description
`logId`	string	Unique identifier for this log entry
`eventTime`	string (ISO 8601)	Timestamp of the event
`source`	string	The Knowledge subsystem that emitted the event
`eventType`	string	Full event type name (for example, `com.twilio.knowledge.knowledgebase.created`)
`level`	string	Severity level: `INFO`, `WARNING`, or `ERROR`
`errorCode`	integer	`0` for success; non-zero maps to the Twilio error catalog
`errorReason`	string \| null	Human-readable error description, if applicable
`requestId`	string	Unique ID for the originating API request
`correlationId`	string	Trace ID for correlating events across services
`body`	object	Operation-specific payload

Example log entry

1{
2  "logId": "1775677339108-67cbb62a",
3  "eventTime": "2026-04-08T19:42:19Z",
4  "source": "knowledge",
5  "eventType": "com.twilio.knowledge.knowledgebase.created",
6  "level": "INFO",
7  "errorCode": 0,
8  "errorReason": null,
9  "requestId": "4cc248bf-330b-49e6-9257-c9756e34c267",
10  "correlationId": "4cc248bf-330b-49e6-9257-c9756e34c267",
11  "body": {
12    "created_by": "ACda1bb2889ad6cbe4814c2addbc8a657c",
13    "error_code": null,
14    "interface_type": "API",
15    "latency_ms": 251,
16    "knowledge_base_id": "know_knowledgebase_00000000000000000000000000"
17  }
18}

Error and warning logs

Enterprise Knowledge logs errors and warnings for create, search, update, delete, and index operations. Enterprise Knowledge structures every error log entry to help you identify the root cause and take corrective action.

Error log fields

Failed and partial-success events include error_code and display_message in their body. Follow the error_code value to its entry in the Twilio API error reference, which provides:

A plain-language description of the error
A list of possible causes
Suggested actions to resolve the issue

(information)

Info

Error details are also viewable directly in the Twilio Console Debugger.

Knowledge error codes

The following error codes appear in Enterprise Knowledge event logs:

Code	Message	Level
420001	Knowledge could not be created	`ERROR`
420002	Partial knowledge refresh	`WARNING`
420003	Search query failed	`ERROR`
420004	Content exceeds knowledge size limits	`ERROR`
420005	Text resource ingest failed	`ERROR`
420006	Failed to crawl or fetch the URL	`ERROR`
420007	URL crawl partially timed out	`WARNING`
420008	File input failed	`ERROR`
420009	Partial update, content skipped	`WARNING`
420010	Knowledge resource update failed	`ERROR`
420011	Knowledge resource deletion failed	`ERROR`
420012	Knowledge update validation failed	`ERROR`
420013	Knowledge base update failed	`ERROR`
420014	Knowledge base deletion failed	`ERROR`

Enterprise Knowledge observability

Capabilities

Access logs

Product event logs

Knowledge events

Knowledge base events

Info

Deprecated event names

Knowledge event payloads

The com.twilio.knowledge.knowledge.created event

The com.twilio.knowledge.knowledge.searched event

The com.twilio.knowledge.knowledge.updated event

The com.twilio.knowledge.knowledge.deleted event

The com.twilio.knowledge.knowledge.indexed event

Log entry schema

Example log entry

Error and warning logs

Error log fields

Info

Knowledge error codes

The `com.twilio.knowledge.knowledge.created` event

The `com.twilio.knowledge.knowledge.searched` event

The `com.twilio.knowledge.knowledge.updated` event

The `com.twilio.knowledge.knowledge.deleted` event

The `com.twilio.knowledge.knowledge.indexed` event