For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.v2.insights.query.byRegion(region).logs.search.post(body: Logs_search_request, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | Logs_search_response>

Description

To search log records in a region, send a POST request to /v2/insights/query/{region}/logs/search with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. pagination.limit defaults to 100 and is clamped to 1000. Cursor pagination requires ordering by timestamp alone; other sort orders return has_more: false and cannot be paged.

Parameters

Path Parameters

region string required

Example: nyc3

The datacenter region slug for the query.

Request Body

timeRange object required

An inclusive query time window.

Show child properties

from object required

A single point in time. Exactly one value form is set per message.

Show child properties

absolute string optional

Example: 2026-09-01T00:00:00Z

An absolute timestamp. Accepts RFC3339/RFC3339Nano strings or Unix seconds/nanoseconds as decimal strings.

relative string optional

Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-1h or now+30m. Supported units are s, m, h, d, and w.

unixNano string optional

Example: 1756684800000000000

A Unix nanosecond timestamp, encoded as a string to preserve 64-bit precision.

to object required

A single point in time. Exactly one value form is set per message.

Show child properties

absolute string optional

Example: 2026-09-01T00:00:00Z

An absolute timestamp. Accepts RFC3339/RFC3339Nano strings or Unix seconds/nanoseconds as decimal strings.

relative string optional

Example: 1h

A relative time. Use now for the current time, a bare duration such as 1h or 7d to look back from now, or an offset such as now-1h or now+30m. Supported units are s, m, h, d, and w.

unixNano string optional

Example: 1756684800000000000

A Unix nanosecond timestamp, encoded as a string to preserve 64-bit precision.

filter object optional

A boolean filter tree for logs queries. Exactly one node is set per message.

Show child properties

condition object optional

A single field comparison in a logs filter expression.

Show child properties

field object required

A reference to a logical field for filters, ordering, grouping, or facets.

Show child properties

name string required

Example: service.name

The field name. Intrinsic columns include timestamp, severity_text, severity_number, body, trace_id, span_id, and trace_flags. The dotted shorthands service.name, resource.type, and resource.urn are also supported. Arbitrary resource or log attributes can be accessed with ResourceAttributes['key'] or LogAttributes['key'].

scope string optional

The attribute scope to resolve the field against. Omit to let the server apply its default mapping for the field name.

One of: FIELD_SCOPE_RESOURCE, FIELD_SCOPE_ATTRIBUTES

operator string required

The comparison operator.

One of: FILTER_OPERATOR_EQ, FILTER_OPERATOR_NEQ, FILTER_OPERATOR_IN, FILTER_OPERATOR_EXISTS, FILTER_OPERATOR_GTE, FILTER_OPERATOR_LTE

value object optional

A typed literal or list value for a filter condition. Exactly one kind is set per message.

Show child properties

stringValue string optional

Example: droplet-123

numberValue number optional

Example: 42

boolValue boolean optional

Example: true

stringArrayValue object optional

Additional nested properties are not shown.

numberArrayValue object optional

Additional nested properties are not shown.

and object optional

Show child properties

expressions array of objects required

Additional nested properties are not shown.

or object optional

Show child properties

expressions array of objects required

Additional nested properties are not shown.

not object optional

A boolean filter tree for logs queries. Exactly one node is set per message.

Additional nested properties are not shown.

textSearch object optional

A substring search across the log body, service name, and resource URN.

Show child properties

query string required

Example: error

The search string.

orderBy array of objects optional

Sort clauses applied to the result set.

Show child properties

field object required

A reference to a logical field for filters, ordering, grouping, or facets.

Show child properties

name string required

Example: service.name

The field name. Intrinsic columns include timestamp, severity_text, severity_number, body, trace_id, span_id, and trace_flags. The dotted shorthands service.name, resource.type, and resource.urn are also supported. Arbitrary resource or log attributes can be accessed with ResourceAttributes['key'] or LogAttributes['key'].

scope string optional

The attribute scope to resolve the field against. Omit to let the server apply its default mapping for the field name.

One of: FIELD_SCOPE_RESOURCE, FIELD_SCOPE_ATTRIBUTES

direction string optional

The sort direction. Omit to use the server default.

One of: SORT_DIRECTION_ASC, SORT_DIRECTION_DESC

pagination object optional

Opaque keyset pagination request. Cursors are only valid when ordering by timestamp alone.

Show child properties

limit integer optional

Example: 100

Maximum number of results to return. Defaults to 100 and is clamped to 1000.

Default: 100

Min: 1

Max: 1000

cursor string optional

Example: eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ

Opaque cursor from a previous response.

Request Sample

import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.insights.query
    .byRegion("nyc3").logs.search.post({
    timeRange: {
        from: {
            absolute: new Date("2026-09-01T00:00:00Z"),
            relative: "1h",
            unixNano: "1756684800000000000",
        },
        to: {
            absolute: new Date("2026-09-01T00:00:00Z"),
            relative: "1h",
            unixNano: "1756684800000000000",
        },
    },
    filter: {
        condition: {
            operator: "FILTER_OPERATOR_EQ",
        },
        and: {
            expressions: [],
        },
        or: {
            expressions: [],
        },
        textSearch: {
            query: "error",
        },
    },
    orderBy: [
        {
            direction: "SORT_DIRECTION_DESC",
        },
    ],
    pagination: {
        limit: 100,
        cursor: "eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ",
    },
});

Response Example

{
  "data": [
    {
      "timestamp": "2026-09-01T00:00:00Z",
      "severity_number": 17,
      "severity_text": "Error",
      "body": "Connection timeout",
      "trace_id": "abc123",
      "span_id": "def456",
      "service_name": "api-gateway",
      "resource": {
        "do.component": "droplet",
        "do.droplet.id": "12345678"
      },
      "attributes": {
        "http.method": "GET",
        "http.status_code": "504"
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJ0cyI6MTc1NjY4NDgwMDAwMDAwMDAwfQ"
  }
}

More Information

See /v2/insights/query/{region}/logs/search in the API reference for additional detail on responses, headers, parameters, and more.