Skip to content
Kapten
Esc
↑↓navigate↵open⌘Jpreview

Query application run logs

Returns the deployment logs of one application run: what Kapten and the image build did while deploying it, and what its agent on the cluster did. For the application’s own output, use the component logs.

Without from or to, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list.

POST/project/{project_id}/environment/{environment_id}/application/{application_id}/runs/{component_run_id}/logs
Authorization
AuthorizationBearer token (JWT) · headerrequired

JWT token passed in the Authorization header using the Bearer <token> format.

Path parameters
project_iduuidrequired

The unique identifier for the project

environment_iduuidrequired

The unique identifier of the environment

application_iduuidrequired

The unique identifier for the application

component_run_iduuidrequired

The unique identifier for the component run

Request body
requiredapplication/json
viewstring

Which run log projection to return.

default: "both"
Allowed:timelinerawboth
fromstring<date-time>

Inclusive lower bound for the run log time range.

tostring<date-time>

Inclusive upper bound for the run log time range.

limitinteger<int32>

Maximum number of most recent raw backend records to query.

min 1 · max 1000 · default: 200
levelsstring[]

Optional log levels to include.

sourcestring[]

Optional timeline event sources to include.

textstring

Optional phrase to search in the log message.

Examples
{
  "view": "timeline",
  "limit": 200,
  "source": [
    "control_plane",
    "agent",
    "builder"
  ]
}
Responses
200

Application run logs retrieved successfully

timelinecomponent_run_timeline_event[]required
Show properties
Array of component_run_timeline_event
timestringrequired

The RFC3339 or RFC3339Nano timestamp returned by Victoria Logs.

levelstringrequired
sourcestringrequired
stepstringrequired
phasestringrequired
backendstring
backend_stepstring
messagestringrequired
metadataobject

Safe structured metadata parsed from kapten_io_metadata when present.

duration_msinteger<int64> | null
run_statusstring
error_kindstring
eventstring

Versioned event discriminator when this is a structured build event.

Allowed:kapten.build.phase
event_versioninteger<int32>
platformstring
Allowed:linux/amd64linux/arm64
publicationstring
Allowed:child_manifestfinal_index
logslogs_query_entry[]required
Show properties
Array of logs_query_entry
msgobject | string | number | boolean | any[] | nullrequired

The normalized log payload as an arbitrary JSON value.

Show properties
One of:
object
object
string
string
number
number
boolean
boolean
any[]
Array of any
any
timestringrequired

The RFC3339 or RFC3339Nano timestamp returned by Victoria Logs.

levelstring

The log level, or an empty string when missing from the source record.

project_idstring

The Kapten project identifier associated with the log entry when present in the source record.

environment_idstring

The Kapten environment identifier associated with the log entry when present in the source record.

component_idstring

The Kapten component identifier associated with the log entry when present in the source record.

component_typestring

The Kapten component type associated with the log entry when present in the source record.

component_run_idstring
component_kindstring
sourcestring
Allowed:control_planeagentbuilder
stepstring
phasestring
backendstring
backend_stepstring
run_statusstring
duration_msinteger<int64>
error_kindstring
metadataobject
eventstring
Allowed:kapten.build.phase
event_versioninteger<int32>
platformstring
Allowed:linux/amd64linux/arm64
publicationstring
Allowed:child_manifestfinal_index
metacomponent_run_logs_metarequired
Show properties
component_run_iduuidrequired

A universally unique identifier (UUID) string

logs_backendstringrequired
Allowed:victoria_logs
default_time_range_appliedbooleanrequired
details_availablebooleanrequired

Whether retained Agent or Builder log details were available for this run.

details_unavailable_reasonstring

Safe user-facing reason returned when run details are unavailable or expired.

pipeline_contextcomponent_run_pipeline_context | null
Show properties
Any of:
component_run_pipeline_context
pipeline_iduuidrequired

A universally unique identifier (UUID) string

pipeline_run_iduuidrequired

A universally unique identifier (UUID) string

stage_run_iduuidrequired

A universally unique identifier (UUID) string

pipeline_component_run_iduuidrequired

A universally unique identifier (UUID) string

stage_component_iduuidrequired

A universally unique identifier (UUID) string

requiredbooleanrequired
timeout_secondsinteger | null
null
null
default

Error

codeinteger<int32>required
messagestringrequired
reasonstring

Optional stable machine-readable reason for programmatic error handling

Request
curl -X POST 'https://api.kapten.io/project/497f6eca-6276-4993-bfeb-53cbbbba6f08/environment/497f6eca-6276-4993-bfeb-53cbbbba6f08/application/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "view": "timeline",
  "limit": 200,
  "source": [
    "control_plane",
    "agent",
    "builder"
  ]
}'
Response
{
  "timeline": [
    {
      "time": "string",
      "level": "string",
      "source": "string",
      "step": "string",
      "phase": "string",
      "backend": "string",
      "backend_step": "string",
      "message": "string",
      "metadata": {},
      "duration_ms": 0,
      "run_status": "string",
      "error_kind": "string",
      "event": "kapten.build.phase",
      "event_version": 0,
      "platform": "linux/amd64",
      "publication": "child_manifest"
    }
  ],
  "logs": [
    {
      "msg": {},
      "time": "string",
      "level": "string",
      "project_id": "string",
      "environment_id": "string",
      "component_id": "string",
      "component_type": "string",
      "component_run_id": "string",
      "component_kind": "string",
      "source": "control_plane",
      "step": "string",
      "phase": "string",
      "backend": "string",
      "backend_step": "string",
      "run_status": "string",
      "duration_ms": 0,
      "error_kind": "string",
      "metadata": {},
      "event": "kapten.build.phase",
      "event_version": 0,
      "platform": "linux/amd64",
      "publication": "child_manifest"
    }
  ],
  "meta": {
    "component_run_id": "6037affb-fb72-4f94-b0fb-f75a6be340e1",
    "logs_backend": "victoria_logs",
    "default_time_range_applied": true,
    "details_available": true,
    "details_unavailable_reason": "string",
    "pipeline_context": {
      "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0",
      "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71",
      "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91",
      "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec",
      "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd",
      "required": true,
      "timeout_seconds": 0
    }
  }
}

Was this page helpful?