API Reference / Contracts
Fetch several contracts' limits with their usage
Returns GetContractLimitUsage for many contracts in one call, alongside the IDs that did not resolve, so a contracts list reads a page of usage at once.
/ contracts. v1. Contracts/ GetContractLimitUsagesRequest body
application/jsonRequired
Request for the configured limits of several contracts in the caller's workspace, each with its current usage, in one call.
contractIds?array<string>Opaque 16-byte identifiers of the contracts, each base64-encoded in JSON. At most 200.
Response body
application/json
Success
notFoundIds?array<string>Requested identifiers with no live contract in the caller's workspace.
usages?array<ContractLimitUsage>One entry per configured limit of each found contract, grouped by contract in request order, then in kind order.
Show attributes
contractId?stringThe contract the limit belongs to.
Format"byte" base64
kind?stringWhich limit this is.
Value in"CONTRACT_"CONTRACT_"CONTRACT_
limit?stringThe configured limit: copies per item, purchases in the window, or cents in the window.
Format"int64"
remaining?stringFor a window, how much is left before it blocks buying (never negative). For max owned per item, how many of the contract's items are still under the limit.
Format"int64"
scope?stringWhat the limit counts across: the whole workspace for max owned per item, this contract alone for the two windows.
Value in"CONTRACT_"CONTRACT_
used?stringFor a window, the purchases or cents counted in it now. For max owned per item, how many of the contract's items the workspace already holds at or over the limit, which buying skips.
Format"int64"
windowResetsAt?stringFor a window with counted purchases, when the oldest of them leaves the window and frees room. Unset for max owned per item and for an empty window.
Format"date-time"
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
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/GetContractLimitUsages" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contractIds": [
"EBESExQVFhcYGRobHB0eHw=="
]
}'const res = await fetch("https://api.goldmine.to/contracts.v1.Contracts/GetContractLimitUsages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"contractIds": [
"EBESExQVFhcYGRobHB0eHw=="
]
}),
});
const data = await res.json();body := strings.NewReader(`{
"contractIds": [
"EBESExQVFhcYGRobHB0eHw=="
]
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/contracts.v1.Contracts/GetContractLimitUsages", 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/GetContractLimitUsages",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"contractIds": [
"EBESExQVFhcYGRobHB0eHw=="
]
},
)
data = res.json(){
"usages": [
{
"contractId": "EBESExQVFhcYGRobHB0eHw==",
"kind": "CONTRACT_LIMIT_KIND_SPEND_WINDOW",
"scope": "CONTRACT_LIMIT_SCOPE_CONTRACT",
"limit": "50000",
"used": "12500",
"remaining": "37500",
"windowResetsAt": "2026-11-12T18:30:00Z"
}
],
"notFoundIds": []
}{
"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": "internal",
"message": "An internal server error occurred."
}