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.
/ contracts. v1. Contracts/ ListSnapshotsRequest body
application/jsonRequired
Request for one page of a contract's snapshots.
contractIdstringContract to list snapshots from.
Format"byte" base64
cursor?stringOpaque pagination cursor from a previous ListSnapshotsResponse. Empty for the first page.
descending?booleanOrder descending instead of ascending.
limit?integerMaximum number of snapshots to return. Server caps this at a service-defined upper bound.
Format"int32"
sortField?stringField to order the page by. Unspecified orders by creation time.
Value in"SNAPSHOT_
Response body
application/json
Success
nextCursor?stringCursor 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?stringNumber of intents newly added in this snapshot, compared to the previous one.
Format"int64"
contractId?stringContract this snapshot evaluated.
Format"byte" base64
createdAt?stringWhen the snapshot was created.
Format"date-time"
createdBy?stringActor 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?stringNumber of intents removed in this snapshot, compared to the previous one.
Format"int64"
deletedAt?stringWhen the snapshot was soft-deleted, if it has been.
Format"date-time"
id?stringSnapshot sequence number, monotonic per contract. The first snapshot is 1.
Format"int64"
inputConfigVersion?stringCaptured contract configuration version used by the evaluation that created this snapshot. Unset when unknown. An explicit zero is a known version.
Format"int64"
inputGeneration?stringOpaque 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?stringTotal number of intents in effect after this snapshot.
Format"int64"
updated?stringNumber of intents whose price or float window changed in this snapshot, compared to the previous one.
Format"int64"
updatedAt?stringWhen the snapshot was last modified.
Format"date-time"
updatedBy?stringSame actor as created_by. A snapshot is insert-only, so the two are always stamped identically.
Format"byte" base64
workspaceId?stringWorkspace the snapshot's contract belongs to.
Format"byte" base64
application/json
The request was malformed, such as a missing required field or an unparseable cursor.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request lacks a valid API key in the Authorization header.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The API key is not allowed to perform this action on this workspace.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
The request was rate limited. Slow down and retry later.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
application/json
An internal server error occurred.
codestringThe Connect error code, such as "not_found".
details?array<object>Optional machine-readable error details.
messagestringA human-readable description of the error.
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": ""
}'const res = await fetch("https://api.goldmine.to/contracts.v1.Contracts/ListSnapshots", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"limit": 50,
"cursor": ""
}),
});
const data = await res.json();body := strings.NewReader(`{
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"limit": 50,
"cursor": ""
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/contracts.v1.Contracts/ListSnapshots", body)
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("CSTRADER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)import os, requests
res = requests.post(
"https://api.goldmine.to/contracts.v1.Contracts/ListSnapshots",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"limit": 50,
"cursor": ""
},
)
data = res.json(){
"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"
}{
"code": "invalid_argument",
"message": "The request was malformed, such as a missing required field or an unparseable cursor."
}{
"code": "unauthenticated",
"message": "The request lacks a valid API key in the Authorization header."
}{
"code": "permission_denied",
"message": "The API key is not allowed to perform this action on this workspace."
}{
"code": "resource_exhausted",
"message": "The request was rate limited. Slow down and retry later."
}{
"code": "internal",
"message": "An internal server error occurred."
}