cURL

curl --fail-with-body -sS -X POST 'https://assets-testnet.lumeus.dev/snapshots' \
  -H "Authorization: Bearer $LUMEUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"holdings","address":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR","as_of_ledger":5300000}'

// Node 18+ (ES module)
const res = await fetch('https://assets-testnet.lumeus.dev/snapshots', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000
  }),
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.post(
    "https://assets-testnet.lumeus.dev/snapshots",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"},
    json={
        "kind": "holdings",
        "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
        "as_of_ledger": 5300000
    },
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "id": "00000000-0000-4000-8000-000000000000",
  "kind": "holdings",
  "params": {
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000
  },
  "status": "completed",
  "created_at": "2026-10-22T09:15:04Z",
  "finished_at": "2026-10-22T09:15:31Z",
  "result": {
    "source": "history",
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000,
    "checkpoint": 0,
    "ledgers_replayed": 0,
    "records": [
      {
        "asset": "native",
        "kind": "native",
        "source": "ledger_entry",
        "balance": "7542806429.6530056",
        "balance_raw": "75428064296530056",
        "decimals": 7,
        "archived": false,
        "last_modified_ledger": 5299980
      }
    ],
    "zero_balances": 0,
    "truncated": false,
    "entries_scanned": 3,
    "timings": {
      "bootstrap_ms": 0,
      "replay_ms": 0,
      "total_ms": 41
    }
  }
}

Start a snapshot job

Starts a job that computes an address’s holdings or an asset’s holders at any past ledger from 63 on, including before bootstrap_ledger, from a history-archive checkpoint plus at most 63 replayed ledgers. Use it when an as_of_ledger read answers 409. The job runs in the background: poll GET /snapshots/{id} (the Location header). Holders results list at most the top 10,000 holders. An organization can have at most 5 jobs queued or running. Credit class assets-snapshot: 50 per job, charged on completion and released on failure. Publishable keys are not allowed.

POST

/

snapshots

cURL

curl --fail-with-body -sS -X POST 'https://assets-testnet.lumeus.dev/snapshots' \
  -H "Authorization: Bearer $LUMEUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"holdings","address":"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR","as_of_ledger":5300000}'

// Node 18+ (ES module)
const res = await fetch('https://assets-testnet.lumeus.dev/snapshots', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LUMEUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000
  }),
});
console.log(res.status, JSON.stringify(await res.json(), null, 2));

import json
import os

import requests

res = requests.post(
    "https://assets-testnet.lumeus.dev/snapshots",
    headers={"Authorization": f"Bearer {os.environ['LUMEUS_API_KEY']}"},
    json={
        "kind": "holdings",
        "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
        "as_of_ledger": 5300000
    },
    timeout=30,
)
print(res.status_code, json.dumps(res.json(), indent=2))

{
  "id": "00000000-0000-4000-8000-000000000000",
  "kind": "holdings",
  "params": {
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000
  },
  "status": "completed",
  "created_at": "2026-10-22T09:15:04Z",
  "finished_at": "2026-10-22T09:15:31Z",
  "result": {
    "source": "history",
    "kind": "holdings",
    "address": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR",
    "as_of_ledger": 5300000,
    "checkpoint": 0,
    "ledgers_replayed": 0,
    "records": [
      {
        "asset": "native",
        "kind": "native",
        "source": "ledger_entry",
        "balance": "7542806429.6530056",
        "balance_raw": "75428064296530056",
        "decimals": 7,
        "archived": false,
        "last_modified_ledger": 5299980
      }
    ],
    "zero_balances": 0,
    "truncated": false,
    "entries_scanned": 3,
    "timings": {
      "bootstrap_ms": 0,
      "replay_ms": 0,
      "total_ms": 41
    }
  }
}

Authorizations

Authorization

string

header

required

Send Authorization: Bearer <key>, the same keys as Activity and RPC. Testnet: lum_test_…; Mainnet: lum_live_…. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable lum_pub_… keys work only on the routes marked "Publishable keys allowed", from an allowed browser origin.

Headers

Idempotency-Key

string

Optional, 8 to 128 characters. Resending the same key with the same request returns the existing job (200, no new charge); the same key with a different request returns 409. It deduplicates on every plan, with no expiry.

Required string length: 8 - 128

Example:

"retry-0001-2026-10-22"

Body

application/json

kind

enum<string>

required

holdings: one address's holdings; holders: an asset's ranked holders.

Available options:

holdings,

holders

as_of_ledger

integer

required

Any past ledger from 63 up to the latest applied ledger; it may be before bootstrap_ledger.

Required range: x >= 63

address

string

G or C address. Required for holdings.

asset

string

Asset ID (native, CODE:ISSUER, a C… token contract or pool:<64 hex>). Required for holders.

Response

The same Idempotency-Key and request were sent before: the existing job, not charged again.

id

string<uuid>

required

kind

enum<string>

required

Available options:

holdings,

holders

params

object

required

Show child attributes

status

enum<string>

required

Available options:

queued,

running,

completed,

failed

created_at

string<date-time>

required

muxed_input

string

The M… address from the request, when one was sent.

result

object

A flat list of balances at as_of_ledger. Unlike the live routes it has no read_view, _links or paging.

Show child attributes

error

string

Why the job failed.

finished_at

string<date-time>