Get the captures for a trace

Returns the request/response body/headers for a trace ID as part of the session capture

get

Path Parameters

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

debugSessionIdstring(uuid)required

Debug Session identifier

Example:d32d905a-ed33-46a3-a093-d8f536af9a8a

traceIdstringrequired

Unique identifier of the trace.

Example:0b419ff749c4dabf5f45b0cfee053bc1

Response

application/json

The capture content for a trace ID

TraceCaptures

Represents the request/response captures associated with a trace

request_bodystring

The captured request body

request_headersobject

The captured request headers

response_bodystring

The captured response body

response_headersobject

The captured response headers

get/control-planes/{controlPlaneId}/o11y/debug-sessions/{debugSessionId}/traces/{traceId}/captures
 
application/json

Download traces and logs for a trace ID

Downloads traces and associated logs and payload for a specific trace ID in a debug session as a ZIP file.

The ZIP file contains separate JSON files:

  • trace.json: Complete trace data (same format as getTraceById)
  • logs.json: Associated logs array (same format as log search responses)
  • captures.json: Request/response captures (same format as getCapturesForTrace)

Files are only included based on the request parameters (include_logs, include_captures).

post

Path Parameters

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

debugSessionIdstring(uuid)required

Debug Session identifier

Example:d32d905a-ed33-46a3-a093-d8f536af9a8a

traceIdstringrequired

Unique identifier of the trace.

Example:0b419ff749c4dabf5f45b0cfee053bc1

Body

application/json

TraceDownloadRequest

Request payload for downloading traces and logs for a specific trace ID

include_logsbooleanrequired

Whether to include associated logs in the ZIP file

Default:true

log_filtersobject

Key-value pairs to filter logs based on specific attributes.

* Additional properties are NOT allowed.
Show Child Parameters
include_capturesbooleanrequired

Whether to include request/response captures in the ZIP file

Default:true

formatstring

The format for the downloaded data (currently only ZIP is supported)

Allowed values:zip

Default:zip

Response

application/zip

ZIP file containing separate JSON files for traces, logs, and captures for the specified trace ID

string

ZIP file containing separate JSON files (trace.json, logs.json, captures.json)

post/control-planes/{controlPlaneId}/o11y/debug-sessions/{debugSessionId}/traces/{traceId}/download

Body

{ "include_logs": true, "include_captures": true, "format": "zip", "log_filters": { "log_type": { "neq": "access" } } }
 
application/zip

Mark Target Completed (Internal)

Marks the target as completed in an active debug session

post

Path Parameters

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

debugSessionIdstring(uuid)required

Debug Session identifier

Example:d32d905a-ed33-46a3-a093-d8f536af9a8a

targetIdstring(uuid)required

Unique identifier of the data plane node.

Example:d32d905a-ed33-46a3-a093-d8f536af9a8a

Response

application/json

Debug Session Done Response

object
post/internal/control-planes/{controlPlaneId}/o11y/debug-sessions/{debugSessionId}/targets/{targetId}/done
 
application/json

Session Logs

Debug Session Logs APIs

Search Logs

Search logs for a specific debug session in a control plane

post

Query Parameters

page[size]integer

The maximum number of items to include per page. The last page of a collection may include fewer items.

Example:10

page[after]string

Request the next page of data, starting with the item after this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

page[before]string

Request the next page of data, starting with the item before this parameter.

Example:ewogICJpZCI6ICJoZWxsbyB3b3JsZCIKfQ

Path Parameters

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

debugSessionIdstring(uuid)required

Debug Session identifier

Example:d32d905a-ed33-46a3-a093-d8f536af9a8a

Body

application/json

LogSearchRequest

Represents the request payload for searching logs in a debug session.

startstring(date-time)

The start time for the log search query. Must be in RFC-3339 format.

endstring(date-time)

The end time for the log search query. Must be in RFC-3339 format.

node_idarray[string](uuid)unique-items

A list of data plane node IDs to filter logs.

span_idarray[string]unique-items

A list of identifier of the span within a trace to filter logs.

trace_idarray[string]unique-items

A list of identifier of the trace to filter logs.

severity_textarray[string]unique-items

A list of severity levels to filter logs (e.g., ERROR, WARN).

severity_numberarray[integer]unique-items

A list of numeric severity levels to filter logs (e.g., 17 for ERROR, 15 for WARN).

attributesobject

Key-value pairs to filter logs based on specific attributes.

* Additional properties are NOT allowed.
Show Child Parameters
order_byobject

Specifies the sorting order for the logs in the response.

Show Child Parameters

Response

application/json

Matching OTel data plane logs

LogSearchResponse

metaobject
Show Child Parameters
logsarray[object]required

Represents a log entry based on the OpenTelemetry (OTel) data model.

Example:{"span_id":"090a0b0c0d0e0f00","trace_id":"ff0102030405060708090a0b0c0d0e0f","timestamp":"2025-04-22T14:12:00.123Z","observed_timestamp_ns":1749449968177456600,"severity_text":"ERROR","severity_number":17,"body":"Timeout from downstream service","attributes":{"user_id":"user-123","request_id":"abc-123","check_number":2344},"resource":{"attributes":{"service.name":"Kong","service.version":"1.2.3"}},"scope":{"attributes":{"log_body_decryption_error\"":"error decrypting log"}}}

Show Child Parameters
post/control-planes/{controlPlaneId}/o11y/debug-sessions/{debugSessionId}/logs/search

Body

{ "start": "2025-04-22T00:00:00Z", "end": "2025-04-22T23:59:59Z", "node_id": [ "d32d905a-ed33-46a3-a093-d8f536af9a8a", "ae853602-23c7-4218-9071-82fdef3a1efe" ], "span_id": [ "090a0b0c0d0e0f00" ], "trace_id": [ "ff0102030405060708090a0b0c0d0e0f" ], "severity_text": [ "ERROR", "WARN" ], "severity_number": [ 17, 15 ], "attributes": { "log_type": { "neq": "access" }, "introspection_name": { "in": [ "request", "response" ] }, "plugin_name": { "eq": "my-plugin" } }, "order_by": { "field": "timestamp", "direction": "desc" } }
 
application/json