Logging API

Use the Logging REST API to retrieve log entries programmatically for a given time range with optional filters.

The API returns as many as 200 log entries per request and supports pagination through the offset parameter. You can also construct API requests directly from the Instana® UI. To generate a ready-to-use curl command, apply your desired filters and click API Query.

Endpoint

Replace <Host> with your Instana base URL (for example, https://<unit>.<tenant>.instana.io for SaaS tenants).

POST <Host>/api/logging/logs/getLogs/v1

Authentication

Pass an API token in every request as a header:

Authorization: apiToken YOUR_API_TOKEN

To create or manage API tokens, from the navigation menu in the Instana UI, select Settings > API Tokens.

Request body

The request body must be a JSON object (Content-Type: application/json) that conforms to the LogsQuery schema.

Required fields

Table 1. Required request body fields
Field Type Description
timeConfig Object Time range configuration. See timeConfig.
retrievalSize Integer Maximum number of log entries to return. Range: 1–200. The API automatically reduces values greater than 200 to 200.
orderDirection String Sort order. ASC returns oldest entries first; DESC returns newest entries first.
requestedTags Array of strings Tag names to include in the response. Maximum 10 tags. See Available tags.

Optional fields

Table 2. Optional request body fields
Field Type Description
offset Integer Number of log entries to skip before returning results. Defaults to 0. Permitted range: 0–2000. Use this field to paginate through results.
tagFilterExpression Object Filter criteria for log attributes. See tagFilterExpression.

timeConfig object

Table 3. timeConfig fields
Field Type Description
to Long End of the time range as a Unix timestamp in milliseconds.
windowSize Long Duration of the time range in milliseconds (for example, 3600000 for one hour).
focusedMoment Long The focused point in time as a Unix timestamp in milliseconds.
autoRefresh Boolean Whether to enable automatic refresh.

tagFilterExpression object

Use tagFilterExpression to narrow results by log attributes. The expression uses a tree structure of EXPRESSION and TAG_FILTER nodes.

Table 4. tagFilterExpression fields
Field Type Description
type String EXPRESSION for a logical grouping, or TAG_FILTER for a single filter condition.
logicalOperator String Applies when type is EXPRESSION. AND requires all conditions to match; OR requires any condition to match.
elements Array Child nodes, each of which is either an EXPRESSION or a TAG_FILTER.
name String Applies when type is TAG_FILTER. The tag name to filter on (for example, log.level).
operator String Applies when type is TAG_FILTER. The comparison operator, for example, EQUALS, CONTAINS. See Filter operators.
entity String Applies when type is TAG_FILTER. Use NOT_APPLICABLE for log-native tags; use DESTINATION for service-related tags.
value String Applies when type is TAG_FILTER. The value to match against.

Filter operators

The following operators are valid values for the operator field in a TAG_FILTER node:

Table 5. Valid filter operator values
Operator Description
EQUALS The tag value exactly matches the specified value.
NOT_EQUAL The tag value does not match the specified value.
CONTAINS The tag value contains the specified string.
NOT_CONTAIN The tag value does not contain the specified string.
STARTS_WITH The tag value starts with the specified string.
ENDS_WITH The tag value ends with the specified string.
NOT_EMPTY The tag value is present and not empty. The API ignores the value field.
IS_EMPTY The tag value is absent or empty. The API ignores the value field.

Available tags

You can request as many as 10 of the following tags in requestedTags:

Table 6. Supported tag names
Tag Description
aws.ecs.containerId ID of the Amazon ECS container.
aws.ecs.containerName Name of the Amazon ECS container.
containerd.containerId ID of the containerd container.
crio.containerId ID of the CRI-O container.
docker.containerId ID of the Docker container.
docker.containerName Name of the Docker container.
expiration.ts.seconds Expiration timestamp of the log entry in seconds.
garden.containerId ID of the Garden container.
host.name Name of the host that produced the log entry.
kubernetes.cluster.name Name of the Kubernetes cluster.
kubernetes.container.name Name of the Kubernetes container.
kubernetes.deployment.name Name of the Kubernetes deployment.
kubernetes.namespace.name Name of the Kubernetes namespace.
kubernetes.node.name Name of the Kubernetes node.
kubernetes.pod.name Name of the Kubernetes pod.
log.applications Application perspectives associated with the log entry.
log.custom Custom attributes attached to the log entry.
log.exception.message Exception message in the log entry.
log.exception.stackTrace Stack trace from the exception in the log entry.
log.exception.type Type of exception in the log entry.
log.file.path Path of the log file that produced the entry.
log.hostId ID of the host that produced the log entry.
log.level Severity level of the log entry (for example, INFO, WARN, ERROR).
log.message Full text of the log message.
log.streamName Name of the log stream.
log.timestamp Timestamp of the log entry in milliseconds.
log.traceId Trace ID associated with the log entry.
process.id ID of the process that produced the log entry.

The Instana UI includes the following tags by default:

  • log.timestamp
  • log.level
  • log.message
  • log.custom

You can modify this list before submitting your request.

Response body

A successful request returns an HTTP 200 response with a JSON response body.

Table 7. Response body fields
Field Type Description
items Array Log entries matching the query criteria.
totalHits Integer Total number of matching log entries across all pages, not just the current page. Use this value to calculate the total number of pages.
canLoadMore Boolean Indicates whether additional log entries are available beyond the current page. When true, increment offset to retrieve the next page.
adjustedTimeFrame Object Reserved for future use. Currently always null.

Pagination

Use retrievalSize and offset together to page through large result sets.

  • With retrievalSize=200 and offset=0, the response contains log entries 1–200.
  • To retrieve the next page, set offset=200 to skip the first 200 entries and return entries 201–400.
  • Increment offset offset by retrievalSize until canLoadMore is false.

Example: If totalHits=450 and retrievalSize=200, there are three pages (200 + 200 + 50).

Error responses

Table 8. HTTP error status codes
HTTP status Description
500 Server error. Returned for invalid request parameters: retrievalSize is missing, less than 0, a non-integer, or offset is negative or non-integer.
503 Service unavailable. The logging service is temporarily unavailable. Retry after some time.

Example request

The following example retrieves the 200 most recent logs from a 1-hour window, filtered by stream name and service, and requests six specific tags:

curl -X POST <Host>/api/logging/logs/getLogs/v1 \
  -H "Authorization: apiToken YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timeConfig": {
      "to": 1711800000000,
      "focusedMoment": 1711800000000,
      "autoRefresh": false,
      "windowSize": 3600000
    },
    "requestedTags": [
      "log.traceId",
      "log.applications",
      "process.id",
      "host.name",
      "docker.containerName",
      "kubernetes.pod.name"
    ],
    "tagFilterExpression": {
      "type": "EXPRESSION",
      "logicalOperator": "AND",
      "elements": [
        {
          "type": "TAG_FILTER",
          "name": "log.streamName",
          "operator": "EQUALS",
          "entity": "NOT_APPLICABLE",
          "value": "log.go"
        },
        {
          "type": "TAG_FILTER",
          "name": "service.name",
          "operator": "EQUALS",
          "entity": "DESTINATION",
          "value": "dispatch"
        }
      ]
    },
    "retrievalSize": 200,
    "offset": 0,
    "orderDirection": "DESC"
  }'

Generating requests from the Instana UI

You can generate a curl command request from the Instana UI based on your current filter selections and time window:

  1. From the navigation menu in the Instana UI, click Logs.
  2. Apply the desired filters and set the time window.
  3. Click API Query.

Instana generates a curl command that reflects your current UI selections, including the default tags log.timestamp, log.level, log.message, and log.custom. Edit the command as needed before running it.

Related topics