---
title: Capture workload data
description: Use load capture to record an anonymized profile of write and query traffic on an InfluxDB 3 Enterprise query node, inspect it, and share it with InfluxData to troubleshoot performance.
url: https://docs.influxdata.com/influxdb3/enterprise/admin/load-capture/
estimated_tokens: 2403
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/admin/load-capture/
date: '2026-08-04T14:39:17-05:00'
lastmod: '2026-08-04T14:39:17-05:00'
---

* InfluxDB 3 Enterprise v3.10.0+

Load capture records an anonymized profile of write requests, query requests,
or both from a running InfluxDB 3 Enterprise cluster.
InfluxData uses the profile to reproduce your workload and troubleshoot write
or query performance while limiting exposure to the identifiers and values that
load capture anonymizes.

A capture anonymizes database names, table names, tag keys, tag values, field
names, string and binary field values, and non-time query literals before
writing them to object storage.
You can preview, download, and inspect a capture locally, then share it with
InfluxData support through your support channel.

> [!Important]
> #### Load capture requires the performance preview and a query-mode node
>
> Load capture requires the[performance upgrade preview](/influxdb3/enterprise/performance-preview/),
> which uses the storage engine upgrade.
> Enable the preview with `--use-pacha-tree` and send `loadcap` requests to a
> node with an explicit `--mode` setting that includes `query`—for example,`--mode query` or `--mode ingest --mode query --mode compact`.
>
> A node using the default `--mode all` configuration returns`404 loadcap not available`, even though it includes query mode.
> Load capture is also unavailable on ingest-, compact-, or process-only nodes
> and on InfluxDB 3 Core.
> For more information about node modes, see[Configure specialized cluster nodes](/influxdb3/enterprise/admin/clustering/)and the [`--mode` option](/influxdb3/enterprise/reference/config-options/#mode).

## Capture types

When you start a capture, choose one of three types:

* **`query`**: records SQL, InfluxQL, and Flight SQL query text sent to the
  query node.
* **`write`**: records anonymized write-ahead log (WAL) files and a snapshot of
  the catalog.
* **`both`**: records query and write artifacts in one profile.

A `write` or `both` capture requires write traffic reaching an ingest node in
the same cluster so the query node observes replicated WAL data.
A `query` capture records queries sent to the query node and does not require
an ingest node.

Constraints:

* Only one capture can run on a node at a time.
  Starting another while one is active returns `409 Conflict`.
* Capture durations use `s`, `m`, or `h` units—for example, `30s`, `5m`, or`1h`.
  The maximum duration is one hour.
* The catalog snapshot in a `write` or `both` capture is taken when the capture*starts*.
  Create and populate the schema you want to capture before you start the
  capture.

## Before you begin

* Identify a node in your cluster running query mode.
* Load capture requires an[admin token](/influxdb3/enterprise/admin/tokens/admin/).

> [!Note]
> Load capture requires the [upgraded storage engine](/influxdb3/enterprise/reference/internals/storage-engine/)—the default for new clusters.
> On clusters that started on 3.10 or earlier, first run the [storage engine upgrade](/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree) (`--upgrade-pacha-tree`).
> Send requests to a node with an explicit `--mode` setting that includes `query`, for example, `--mode query` or `--mode ingest --mode query --mode compact`.
> Load capture isn’t available on a node that uses the default `--mode all` configuration.

Set connection environment variables to target the query node:

```bash
export INFLUXDB3_HOST_URL="https://query-node.example.com:8181"
export INFLUXDB3_AUTH_TOKEN="YOUR_ADMIN_TOKEN"
```

## Capture a workload profile

A capture records only the traffic that arrives while the capture is running.
Queries executed before the capture starts and requests sent after the capture
duration expires are not included in the profile.
Start the capture first, and then run your workload.

Complete the following steps in order:

1. [Start a capture](#start-a-capture)
2. [Send traffic during the capture window](#send-traffic-during-the-capture-window)
3. [Wait for the capture to complete](#wait-for-the-capture-to-complete)
4. [Preview the capture](#preview-the-capture)

### Start a capture

Start a capture and specify the type and duration:

```bash
influxdb3 loadcap start --type both --duration 5m
```

The command returns the profile ID:

```json
{
  "profile_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

Store the profile ID to reference the capture in later commands:

```bash
export PROFILE_ID="550e8400-e29b-41d4-a716-446655440000"
```

The capture is now running for the requested duration.

### Send traffic during the capture window

With the capture running, generate the workload you want to record:

* For a `query` or `both` capture, send SQL, InfluxQL, or Flight SQL queries to
  the query node.
  Only queries that the query node executes while the capture is running are
  recorded—queries that completed before the capture started do not appear in
  the profile.
* For a `write` or `both` capture, send write requests to an ingest node in the
  same cluster so the query node observes replicated WAL data.

### Wait for the capture to complete

The capture stops automatically when the requested duration expires.
List capture profiles and their status:

```bash
influxdb3 loadcap list
```

A profile reports `running`, `complete`, or `aborted` status, along with its
type, requested duration, and creation time.
Wait for the profile to report `complete` before you preview or download it.

### Preview the capture

Preview a profile without downloading it:

```bash
influxdb3 loadcap preview --profile-id "$PROFILE_ID"
```

The preview reports the file count, total size, WAL file count, query count,
and—for `write` and `both` captures—an anonymized catalog summary.

## Inspect before you share

A capture preserves the shape and timing of your workload.
It does not hide every operational characteristic.
Timestamps, numeric and boolean values, schema shape, file counts, query
cadence, query time ranges, and regular expression selectivity are preserved by
design.
Inspect a capture before you share it.

### Download and list the archive

Download the profile as a gzipped tar archive:

```bash
influxdb3 loadcap download \
  --profile-id "$PROFILE_ID" \
  --output "$PROFILE_ID.tar.gz"
```

If you omit `--output`, the CLI writes `{profile_id}.tar.gz`.

List the archive contents:

```bash
tar -tzf "$PROFILE_ID.tar.gz"
```

A `both` profile archive typically contains an anonymized `catalog.json`, a
zstd-compressed `queries.json.zst`, and one or more anonymized `.pt` WAL files:

```text
catalog.json
queries.json.zst
0-00000029.pt
0-00000030.pt
...
```

A `query`-only profile omits `catalog.json` and `.pt` files.
A `write`-only profile omits `queries.json.zst`.

### Extract and inspect

Extract the archive into a temporary directory:

```bash
mkdir -p loadcap-inspect
tar -xzf "$PROFILE_ID.tar.gz" -C loadcap-inspect
```

For a `write` or `both` capture, inspect the anonymized catalog:

```bash
jq . loadcap-inspect/catalog.json
```

Inspect the anonymized queries:

```bash
zstd -dc loadcap-inspect/queries.json.zst | jq .
```

Each query entry contains anonymized query text, the query language, an
anonymized database identifier, and the original timestamp:

```json
{
  "sql": "SELECT \"0-14\", \"0-T\" FROM \"0-gwKPhKqqB5\" WHERE \"0-14\" = 'MHLLIfxq48Mt0'",
  "query_language": "sql",
  "database": "0-RdYkt0Bktle",
  "timestamp": "2026-04-27T12:34:56.789Z"
}
```

The `.pt` files are binary WAL files for InfluxData tooling.
Verify their names and sizes:

```bash
ls -lh loadcap-inspect/*.pt
```

## What load capture anonymizes

Each capture uses a random key that is unique to that capture.
The same original name or value maps to the same anonymized value within one
capture, but a different capture produces different values.
The key is not included in the downloaded profile.

Load capture anonymizes the following:

* Database, table, tag, field family, and field names, replaced with
  deterministic identifiers such as `1-0Dcc2PQ9o7zG`.
* Tag values, string field values, and binary field values in WAL files.
* Identifiers and non-time literals in SQL, InfluxQL, and Flight SQL queries.

Load capture preserves the following:

* Timestamps, numeric field values, and boolean field values.
* Query structure, operators, function names, and time-range literals.
* The InfluxQL `time` identifier and regular expression structure (anchors,
  character classes, and repetition), so query selectivity stays close to
  production.
* Node IDs, modes, core counts, and node state in the catalog snapshot.

Queries that the anonymizer cannot fully parse are replaced with a placeholder
such as `<unsupported:...>` or `<unparseable:...>`.
Statement types without full coverage—including `INSERT`, `UPDATE`, and`DELETE`—are replaced wholesale.
A query capture therefore does not represent write-shaped statement traffic.

## Delete a capture

Delete a profile when you no longer need it:

```bash
influxdb3 loadcap delete --profile-id "$PROFILE_ID"
```

## Share with InfluxData

After you inspect a capture and confirm its contents, provide the archive to
InfluxData support through your existing support channel.
InfluxData uses the profile to reproduce and analyze your workload.

For the load capture HTTP API, see the[Load capture API reference](/influxdb3/enterprise/api/load-capture/).

#### Related

* [Load capture](/influxdb3/enterprise/api/load-capture/)
* [Manage admin tokens](/influxdb3/enterprise/admin/tokens/admin/)
* [Performance tuning](/influxdb3/enterprise/admin/performance-tuning/)
* [Configure specialized cluster nodes](/influxdb3/enterprise/admin/clustering/)