Skip to content

API Reference / Snapshots

List contract snapshots

Returns a paged list of evaluation snapshots for a contract, most recent first. Each page carries hydrated entities, so no follow-up GetSnapshots is needed.

POST/contracts.v1.Contracts/ListSnapshots

Request body

application/jsonRequired

Request for one page of a contract's snapshots.

contractIdstring

Contract to list snapshots from.

Format"byte" base64

cursor?string

Opaque pagination cursor from a previous ListSnapshotsResponse. Empty for the first page.

descending?boolean

Order descending instead of ascending.

limit?integer

Maximum number of snapshots to return. Server caps this at a service-defined upper bound.

Format"int32"

sortField?string

Field to order the page by. Unspecified orders by creation time.

Value in"SNAPSHOT_SORT_FIELD_CREATED_AT"

Response body

application/json

Success

nextCursor?string

Cursor to pass to fetch the next page. Empty when there are no more results.

snapshots?array<Snapshot>

Full snapshots for this page, most recent first. A page carries the hydrated entities, not bare ids, so the caller needs no follow-up GetSnapshots.

Show attributes
added?string

Number of intents newly added in this snapshot, compared to the previous one.

Format"int64"

contractId?string

Contract this snapshot evaluated.

Format"byte" base64

createdAt?string

When the snapshot was created.

Format"date-time"

createdBy?string

Actor whose contract update triggered the evaluation that produced this snapshot. Unset for a background evaluation (a periodic re-evaluation sweep, or a SERVICE own-behalf actor).

Format"byte" base64

deleted?string

Number of intents removed in this snapshot, compared to the previous one.

Format"int64"

deletedAt?string

When the snapshot was soft-deleted, if it has been.

Format"date-time"

id?string

Snapshot sequence number, monotonic per contract. The first snapshot is 1.

Format"int64"

inputConfigVersion?string

Captured contract configuration version used by the evaluation that created this snapshot. Unset when unknown. An explicit zero is a known version.

Format"int64"

inputGeneration?string

Opaque completed-market-feed fingerprint used by the evaluation that created this immutable snapshot. Unset when provenance is unknown. This does not certify independently mutable catalog, primitive observations, sales, or exchange rates. Reusing a snapshot preserves its original generation.

total?string

Total number of intents in effect after this snapshot.

Format"int64"

updated?string

Number of intents whose price or float window changed in this snapshot, compared to the previous one.

Format"int64"

updatedAt?string

When the snapshot was last modified.

Format"date-time"

updatedBy?string

Same actor as created_by. A snapshot is insert-only, so the two are always stamped identically.

Format"byte" base64

workspaceId?string

Workspace the snapshot's contract belongs to.

Format"byte" base64

curl -X POST "https://api.goldmine.to/contracts.v1.Contracts/ListSnapshots" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "EBESExQVFhcYGRobHB0eHw==",
    "limit": 50,
    "cursor": ""
  }'
{
  "snapshots": [
    {
      "contractId": "EBESExQVFhcYGRobHB0eHw==",
      "id": "7",
      "workspaceId": "AAECAwQFBgcICQoLDA0ODw==",
      "added": "42",
      "updated": "5",
      "deleted": "3",
      "total": "118",
      "createdAt": "2026-04-01T12:15:00Z",
      "updatedAt": "2026-04-01T12:15:00Z"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjN9"
}