Hydration API Reference

The hydration service exposes a REST API for replaying archived logs back into Kloudfuse.

All endpoints are available at https://<your-instance>/hydration/query/.

Replace <your-instance> with your Kloudfuse hostname and <sa-token> with a valid Service Account token.

For Service Account token setup, see Authentication. For how archives are configured and what hydration is, see Logs Archive and Hydration.

GET /query/list-archives

Returns the list of archive names available in your configured storage bucket. Use the returned archive names as the archiveName parameter when submitting a hydration job.

List all available archives
curl -H "Authorization: Bearer <sa-token>" \
     "https://<your-instance>/hydration/query/list-archives"
bash
Response
[
  { "name": "k8s-production" },
  { "name": "k8s-staging" },
  { "name": "payment-service" }
]
json

POST /query/hydrate

Submits a new hydration job. The service reads archived log files from the configured storage bucket for the specified time range, applies any filters, and replays matching log lines back into Kloudfuse.

Request body

Field Type Required Description

archiveName

string

Yes

The archive to hydrate. Must match a name returned by /query/list-archives.

startTsMs

int64

Yes

Start of the time range to hydrate, in Unix milliseconds (UTC).

endTsMs

int64

Yes

End of the time range to hydrate, in Unix milliseconds (UTC).

retentionDurationValue

int

No

How long to keep the hydrated logs in Kloudfuse before expiry. Used together with retentionDurationUnit.

retentionDurationUnit

string

No

Time unit for retentionDurationValue. Accepted values: hours, days, weeks.

filters

FilterCriteria[]

No

Array of filter objects. Only log lines that match all filters are replayed. See Filters below. Omit or pass an empty array to hydrate all lines in the time range.

addTags

object

No

Key-value map of additional labels to attach to every replayed log line.

isDryRun

boolean

No

When true, the job runs and reports how many lines would be replayed without actually writing them to Kloudfuse. Useful for validating filters before committing.

Response

Field Description

jobId

UUID of the newly created hydration job. Use this to check progress, pause, resume, or cancel the job.

Examples

Hydrate all logs in a 24-hour window
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/hydrate" \
     -d '{
       "archiveName": "k8s-production",
       "startTsMs": 1720000000000,
       "endTsMs":   1720086400000
     }'
bash
Response
{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }
json
Hydrate only error logs from the payment service
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/hydrate" \
     -d '{
       "archiveName": "k8s-production",
       "startTsMs": 1720000000000,
       "endTsMs":   1720086400000,
       "filters": [
         { "field": "service",  "operation": "eq", "value": "payment-service", "type": "labels" },
         { "field": "level",    "operation": "eq", "value": "error",           "type": "labels" }
       ]
     }'
bash
Hydrate logs whose message matches a regex pattern
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/hydrate" \
     -d '{
       "archiveName": "k8s-production",
       "startTsMs": 1720000000000,
       "endTsMs":   1720086400000,
       "filters": [
         { "operation": "regex", "value": ".*connection (refused|timeout).*", "type": "message" }
       ]
     }'
bash
Dry run to count matching lines before committing
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/hydrate" \
     -d '{
       "archiveName": "k8s-production",
       "startTsMs": 1720000000000,
       "endTsMs":   1720086400000,
       "isDryRun": true,
       "filters": [
         { "field": "namespace", "operation": "regex", "value": "prod-.*", "type": "labels" }
       ]
     }'
bash

Filters

Each filter object in the filters array has the following fields. All filters are combined with logical AND — a log line must satisfy every filter to be replayed.

Field Type Required Description

field

string

Conditional

The label or agent-extracted facet name to match against (for example, namespace, service, level). Required when type is labels. Must be omitted or empty when type is message.

operation

string

Yes

The comparison operation. See Operations below.

value

string

Yes

The string value to compare against. For regex and nregex operations this is a Go regular expression pattern. The pattern is automatically anchored to the full field value — write prod-.* rather than prod- to match values that start with "prod-".

type

string

No (default: labels)

Which part of the log line the filter applies to.
labels — match against the log’s label map and agent-extracted facets. For positive operations (eq, contains, regex), the filter passes if the value is found in either map. For negative operations (neq, ncontains, nregex), the filter passes only if the condition holds in both maps.
message — match against the raw log message string.

Operations

Operation Description

eq

Exact equality. The field value must equal value exactly.

neq

Not equal. The field value must not equal value.

contains

Substring match. The field value must contain value as a substring.

ncontains

Negative substring match. The field value must not contain value as a substring.

regex

Regular expression match. The full field value must match the pattern. The pattern is anchored: prod-.* matches prod-us-east but not staging-prod-us.

nregex

Negative regular expression match. The full field value must not match the pattern.

POST /query/job-progress

Returns the current status and progress of a hydration job.

Request body

Field Type Required Description

jobId

string

Yes

UUID of the job returned by /hydrate.
Check job progress
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/job-progress" \
     -d '{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }'
bash
Response
{
  "jobId":      "550e8400-e29b-41d4-a716-446655440000",
  "jobStatus":  "HYDRATING",
  "jobSummary": "{\"totalHours\":24,\"completedHours\":6,\"totalLines\":0,\"filteredLines\":0}"
}
json

Job status values:

Status Description

INIT

Job is queued and waiting for a worker.

HYDRATING

Job is actively running.

PAUSED

Job was paused by a /query/pause call.

DONE

Job completed successfully.

FAILED

Job encountered an error. Check errorMsg in the /query/list-jobs response for details.

CANCELED

Job was canceled by a /query/cancel call.

POST /query/list-jobs

Returns a list of hydration jobs, optionally filtered by time range.

Request body (all fields optional)

Field Type Description

startTsMs

int

Return only jobs whose archive start time is at or after this Unix millisecond timestamp.

endTsMs

int

Return only jobs whose archive end time is at or before this Unix millisecond timestamp.

count

int

Maximum number of jobs to return. Defaults to all.

offset

int

Number of jobs to skip (for pagination).
List the 10 most recent jobs
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/list-jobs" \
     -d '{ "count": 10 }'
bash
Response
[
  {
    "jobId":            "550e8400-e29b-41d4-a716-446655440000",
    "archiveName":      "k8s-production",
    "archiveStartTsMs": 1720000000000,
    "archiveEndTsMs":   1720086400000,
    "archiveFilters":   [{ "field": "level", "operation": "eq", "value": "error", "type": "labels" }],
    "isDryRun":         false,
    "jobStatus":        "DONE",
    "jobSummary":       "...",
    "createdAtMs":      1720100000000,
    "lastUpdatedAtMs":  1720103600000,
    "errorMsg":         null
  }
]
json

POST /query/pause

Pauses a running hydration job. The job can be resumed later with /resume. Only jobs in HYDRATING status can be paused.

Request body

Field Type Required Description

jobId

string

Yes

UUID of the job to pause.
Pause a job
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/pause" \
     -d '{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }'
bash
Response
{
  "jobId":          "550e8400-e29b-41d4-a716-446655440000",
  "jobStatus":      "PAUSED",
  "recordsUpdated": 1,
  "message":        "Successfully paused the job"
}
json

POST /query/resume

Resumes a paused hydration job. Only jobs in PAUSED status can be resumed.

Request body

Field Type Required Description

jobId

string

Yes

UUID of the job to resume.
Resume a job
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/resume" \
     -d '{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }'
bash
Response
{
  "jobId":          "550e8400-e29b-41d4-a716-446655440000",
  "jobStatus":      "HYDRATING",
  "recordsUpdated": 1,
  "message":        "Successfully resumed the job"
}
json

POST /query/cancel

Cancels a hydration job. Jobs in DONE or FAILED status cannot be canceled.

Request body

Field Type Required Description

jobId

string

Yes

UUID of the job to cancel.
Cancel a job
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/hydration/query/cancel" \
     -d '{ "jobId": "550e8400-e29b-41d4-a716-446655440000" }'
bash
Response
{
  "jobId":          "550e8400-e29b-41d4-a716-446655440000",
  "jobStatus":      "HYDRATING",
  "recordsUpdated": 1,
  "message":        "Successfully canceled the job"
}
json

Error handling

All endpoints return HTTP 400 for client errors (invalid parameters, job not found, wrong state transition) with a plain-text error message in the response body. HTTP 429 is returned when too many hydration jobs are already running concurrently.

Condition HTTP status Typical response body

Invalid or missing archiveName

400

Archive name=<name> doesn’t exist in the list of archives

Malformed JSON body

400

Can’t unmarshal=…​

jobId not found or wrong status for operation

400

Can’t cancel job=<id>, currentStatus=DONE

Too many concurrent jobs

429

too many concurrent jobs

See also