> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/assets.json post /snapshots openapi: 3.0.3 info: title: Lumeus Assets API version: '2026-09-15' description: >- Lumeus Assets API on Stellar. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet is free: Testnet requests cost no credits and are never billed. Each organization can make 10,000 Testnet requests a day across Activity, Assets and RPC (unlimited on Enterprise); the count resets at 00:00 UTC, and a request over it answers 429 rate_limited with Retry-After set to the seconds until then. Mainnet requests draw from the plan's monthly credits. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer `, 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.** Every response except `GET /readyz` carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON with a machine-readable code (see [errors](/guides/errors)). A path with an empty, `.` or `..` segment answers 400 invalid_request, a trailing slash answers 404 not_found, and a method the path does not accept answers 405 with an Allow header. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://assets-testnet.lumeus.dev description: Testnet (default) - url: https://assets.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: Holdings description: >- Every balance an address holds: XLM, trustlines, liquidity pool shares and contract token balances, live or at a past ledger. - name: Account state description: Claimable balances, open DEX offers and token allowances of an address. - name: Tokens description: >- The token registry (identity, metadata, flags, supply) and the ranked holders of each token. - name: Snapshots description: >- Background jobs that compute holdings or holders at any past ledger, including before the balance history begins. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /snapshots: post: tags: - Snapshots summary: Start a snapshot job description: >- 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. operationId: startSnapshotJob parameters: - name: Idempotency-Key in: header required: false description: >- 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. schema: type: string minLength: 8 maxLength: 128 example: retry-0001-2026-10-22 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SnapshotRequest' example: kind: holdings address: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR as_of_ledger: 5300000 responses: '200': description: >- The same Idempotency-Key and request were sent before: the existing job, not charged again. content: application/json: schema: $ref: '#/components/schemas/SnapshotJob' example: 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 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '202': description: The job was queued; poll its Location. content: application/json: schema: $ref: '#/components/schemas/SnapshotJob' example: id: 00000000-0000-4000-8000-000000000000 kind: holdings params: kind: holdings address: GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR as_of_ledger: 5300000 status: queued created_at: '2026-10-22T09:15:04Z' headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer '400': $ref: '#/components/responses/HTTP400_5' '401': $ref: '#/components/responses/HTTP401' '402': $ref: '#/components/responses/HTTP402' '403': $ref: '#/components/responses/HTTP403_3' '405': $ref: '#/components/responses/HTTP405_9' '409': $ref: '#/components/responses/HTTP409_3' '429': $ref: '#/components/responses/HTTP429_2' '501': $ref: '#/components/responses/HTTP501_2' '503': $ref: '#/components/responses/HTTP503_3' x-codeSamples: - lang: bash label: cURL source: >- 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}' - lang: javascript label: JavaScript source: >- // 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)); - lang: python label: Python source: |- 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)) components: schemas: SnapshotRequest: type: object properties: kind: type: string description: >- holdings: one address's holdings; holders: an asset's ranked holders. enum: - holdings - holders address: type: string description: G or C address. Required for holdings. asset: type: string description: >- Asset ID (native, CODE:ISSUER, a C… token contract or `pool:<64 hex>`). Required for holders. as_of_ledger: type: integer description: >- Any past ledger from 63 up to the latest applied ledger; it may be before bootstrap_ledger. minimum: 63 required: - kind - as_of_ledger additionalProperties: false SnapshotJob: type: object properties: id: type: string format: uuid kind: type: string enum: - holdings - holders params: $ref: '#/components/schemas/SnapshotRequest' muxed_input: type: string description: The M… address from the request, when one was sent. status: type: string enum: - queued - running - completed - failed result: $ref: '#/components/schemas/SnapshotResult' error: type: string description: Why the job failed. created_at: type: string format: date-time finished_at: type: string format: date-time required: - id - kind - params - status - created_at SnapshotResult: type: object properties: kind: type: string enum: - holdings - holders source: type: string description: >- history: computed from the balance history; checkpoint: computed from a history-archive checkpoint plus replayed ledgers. enum: - history - checkpoint address: type: string description: holdings jobs. asset: type: string description: holders jobs. as_of_ledger: type: integer as_of_closed_at: type: string format: date-time checkpoint: type: integer description: Checkpoint ledger used; 0 on the history path. minimum: 0 ledgers_replayed: type: integer minimum: 0 records: type: array items: $ref: '#/components/schemas/SnapshotRecord' description: >- Holdings sorted by asset, or holders by balance descending then holder. At most 10,000 records. holder_count: type: integer description: 'holders jobs: holders with a non-zero balance.' minimum: 0 zero_balances: type: integer minimum: 0 truncated: type: boolean description: >- True when more than 10,000 holders exist; only the top 10,000 are listed and note says how many there are. note: type: string entries_scanned: type: integer format: int64 minimum: 0 timings: type: object properties: bootstrap_ms: type: integer replay_ms: type: integer total_ms: type: integer required: - kind - source - as_of_ledger - checkpoint - ledgers_replayed - records - zero_balances - truncated - entries_scanned - timings description: >- A flat list of balances at as_of_ledger. Unlike the live routes it has no read_view, _links or paging. Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error SnapshotRecord: type: object properties: holder: type: string description: 'holders jobs: the G or C holder.' asset: type: string description: 'holdings jobs: the asset ID.' kind: type: string enum: - native - trustline - pool_share - contract source: type: string description: ledger_entry or token_storage (see the Holding schema). enum: - ledger_entry - token_storage balance: type: string description: Decimal string. balance_raw: type: string description: Exact integer string. pattern: ^-?[0-9]+$ decimals: type: integer minimum: 0 maximum: 38 nullable: true archived: type: boolean last_modified_ledger: type: integer minimum: 0 required: - kind - source - balance - balance_raw - decimals - archived - last_modified_ledger responses: HTTP400_5: description: >- Invalid body (for example as_of_ledger below 63 or after the latest ledger, or a missing address or asset), or an Idempotency-Key outside 8 to 128 characters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_request error: as_of_ledger must be a ledger number of at least 63 request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP401: description: >- Missing, invalid, revoked or expired key, or a key for the other network (code unauthorized). Keys work only on the network they were created for. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized error: missing credentials request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP402: description: >- Mainnet only: the plan's monthly credits are used up on a hard-capped plan (Free; code payment_required). Upgrade, or wait for the next period. Testnet requests cost no credits, so Testnet never answers 402. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: payment_required error: >- monthly credit quota exhausted - top up credits or upgrade your plan request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP403_3: description: >- This key or account cannot call this route (code forbidden): for example a read-only key on a workspace route, or a publishable key on a route or from an origin it does not allow. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: forbidden error: >- publishable keys can only read account holdings and the asset registry; use a secret key on your server request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP405_9: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: 'method GET is not allowed on /snapshots; allowed: POST' request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP409_3: description: >- This Idempotency-Key was already used with a different snapshot request (code conflict). content: application/json: schema: $ref: '#/components/schemas/Error' example: code: conflict error: this Idempotency-Key was used with a different snapshot request request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP429_2: description: >- 5 jobs are already queued or running for this organization (Retry-After 60), the rate limit was reached, or on Testnet the daily Testnet request cap (10,000 requests a day across Activity, Assets and RPC). The code is rate_limited for all three. A rate_limited answer whose Retry-After is greater than 60 is the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. A refused request costs nothing. content: application/json: schema: $ref: '#/components/schemas/Error' examples: Five jobs running: summary: Five jobs already queued or running (Retry-After 60) value: code: rate_limited error: >- too many snapshot jobs queued for this organization; wait for one to finish request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Daily Testnet cap: summary: 'Daily Testnet request cap (Retry-After: seconds until 00:00 UTC)' value: code: rate_limited error: >- daily Testnet request cap of 10000 reached; resets at 00:00 UTC request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Plan rate limit: summary: 'Plan rate limit (Retry-After: a few seconds)' value: code: rate_limited error: rate limit exceeded request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ RateLimit-Limit: description: >- Requests per minute of the bucket that answered: the plan rate, the dashboard session floor of 120, or a publishable key's per-IP rate. schema: type: integer RateLimit-Remaining: description: Whole requests left in the bucket after this one. schema: type: integer RateLimit-Reset: description: Seconds until the bucket is full again. schema: type: integer Retry-After: description: Seconds to wait before retrying. schema: type: integer HTTP501_2: description: Snapshot jobs are not enabled on this host. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_implemented error: snapshot jobs are not available yet request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP503_3: description: >- The state index is not ready (Retry-After 5), or the snapshot queue is full (Retry-After 300). content: application/json: schema: $ref: '#/components/schemas/Error' examples: Queue full: summary: Queue full (Retry-After 300) value: code: unavailable error: the snapshot queue is full; retry later request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 Index not ready: summary: State index not ready (Retry-After 5) value: code: index_not_ready error: asset state is not ready yet; retry later request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: Identifier of this request; also in the error body as request_id. schema: type: string Retry-After: description: Seconds to wait before retrying. schema: type: integer securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer `, 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.