Home / Documentation / API Reference

logging24 HTTP API reference

logging24 exposes its search and query capabilities over HTTP. Use the API when you want direct programmatic access from your own tooling. Use the l24 query CLI when you want the same query model with a more convenient shell interface.

In the docs flow, the API reference comes after the conceptual chapters, the UI, and the CLI because it is primarily an integration reference. New readers should usually understand Querying first, then use this page when they need exact request and response details.

Versioning and compatibility

The search API is versioned. This page describes the versioned search endpoint under your configured API base URL. In hosted setups, the CLI defaults to https://api.logging24.com . Future optional request parameters or response keys are not treated as breaking changes, so API clients should ignore fields they do not understand.

One request from end to end

Request 

curl 'https://api.logging24.com/api/search/v1' \
  -X POST \
  -H 'Authorization: Token ' \
  --data-urlencode 'customer=' \
  --data-urlencode 'regex=.*' \
  --data-urlencode 'type=BACKWARD_RESULTS' \
  --data-urlencode 'beginTime=2022-08-25 21:41:00.000' \
  --data-urlencode 'endTime=2022-08-25 21:57:00.000'

Response 

{
  "fullHash": "7246963916FD189A297F77A970B78E0B144E0B2AAE49BD64C56CF9E161767DF6",
  "events": [
    {
      "time": "1661464551383000000",
      "message": "Aug 25 23:55:51 example-host apache[1254]: Startup completed."
    }
  ],
  "counts": [],
  "totalBlocks": 10044,
  "relevantBlocks": 15,
  "scannedBlocks": 6,
  "failedBlocks": 0,
  "scannedBytes": 24327668,
  "complete": false,
  "stopped": false
}

Authentication

Authenticate with a read token. You can provide it either in the Authorization header as shown above or via the read_token cookie. For permanent integrations, create a dedicated read token rather than relying on a browser session cookie.

Progress model

The API returns partial results while scanning continues asynchronously. Clients should poll the same query again, roughly once per second, until complete becomes true . If polling stops, the backend eventually stops the scan after a short inactivity timeout.

Use scanProgress as the rough progress indicator. Some query types may finish before that estimate reaches its maximum because their stopping condition is satisfied earlier.

Request format

Requests use application/x-www-form-urlencoded in the body.

customer Required. Your technical customer identifier.
prefix0 Default: empty. Restrict results to contexts whose prefix0 starts with this value.
prefix1 Same as prefix0 , for prefix1 .
prefix2 Same as prefix0 , for prefix2 .
prefix3 Same as prefix0 , for prefix3 .
type Default: UNSORTED_RESULTS. Selects the query type.
limit Default: 100. Maximum number of returned elements for result-oriented query types. Valid range: 1 to 10000.
beginTime Default: 1970-01-01 01:00:00. Earliest included event time.
endTime Default: 2254-07-22 01:34:33. Events at or after this time are excluded.
timeBins Default: 1. Number of time buckets. Valid range: 1 to 4096.
regex Required. Full-line regex pattern used for matching.
xSplits Default: empty. Ordered comma-separated thresholds for x-axis histogram bucketing.
ySplits Same as xSplits , for the y dimension.

Timestamp formats

The API accepts ISO-style timestamps. Both YYYY-MM-DDTHH:MM:SS and YYYY-MM-DD HH:MM:SS work. Fractional seconds and timezone offsets are supported. If no timezone offset is present, timestamps are treated as UTC.

Response keys

fullHash Hash of the query parameters, useful for identifying repeated queries.
events Returned log events. Not all query types return events.
events[*].time Event timestamp in nanoseconds since the UNIX epoch.
events[*].context Index into the contexts array.
events[*].message Original log line content as received by ingest, JSON-encoded as needed.
events[*].key Captured key for query types that emit keys.
contexts Deduplicated log contexts for returned events or counts.
contexts[*].customer Customer identifier of the context.
contexts[*].prefix{0,1,2,3} The four log prefixes defining the context.
contexts[*].count Per-context counted values for query types that emit them.
counts Counter array. Layout depends on the query type.
totalBlocks Estimated total number of blocks in the system.
relevantBlocks Blocks that may contribute based on time range and prefixes.
scannedBlocks Blocks scanned so far.
failedBlocks Blocks that failed to scan.
scannedBytes Bytes scanned so far. Billing is based on this value.
scanProgress Approximate scan progress. Complete scans reach 4294967296.
complete Becomes true when the result is fully computed.
stopped Becomes true once backend scanning has actually stopped.
error Error description when the request could not be processed.
errorCode Machine-readable error identifier for selected failures.

Error code currently documented: BAD_TOKEN for rejected authentication tokens.

Query types

UNSORTED_RESULTS

Returns matching events without ordering guarantees.

Use case: checking whether a pattern exists at all inside a time interval.

BACKWARD_RESULTS

Returns matching events in reverse chronological order.

Use case: interactive exploration of the newest matching logs first.

EXACT_COUNTS_BINNED

Counts matching events per time bin. The first element in counts is the earliest time bin and the last is the latest one. limit does not apply.

Use case: count how often a pattern appears over time.

EXACT_XY_HISTOGRAM_BINNED

Counts matching events per time bin and per x/y bucket, based on xSplits , ySplits , and regex captures such as (?...) and (?...) . limit does not apply.

Use case: plot a metric over time or show the relationship between two captured values.

BACKWARD_RESULTS_ONE_PER_KEY31

Returns the last event per captured key, up to limit unique keys. The regex must contain a (?...) capture.

Use case: fetch the latest status line, metric set, or event for each host, pod, or other extracted key.

Related links