Skip to content

API Reference / Contracts

Get profit over time for several contracts

Returns each contract's profit per day, week or month over one range, for up to 100 contracts in one read.

POST/contracts.v1.Contracts/GetContractPnLPeriods

Request body

application/jsonRequired

Request for the profit per period of up to 100 contracts in the caller's workspace.

contractIdsarray<string>

The contracts to read, at most 100. A contract outside the caller's workspace, or deleted, is left out of the response.

endTimestring

End of the period range.

Format"date-time"

granularitystring

Time bucket size for every series.

Value in"PNL_GRANULARITY_DAY""PNL_GRANULARITY_WEEK""PNL_GRANULARITY_MONTH""PNL_GRANULARITY_HOUR"

startTimestring

Start of the period range.

Format"date-time"

Response body

application/json

Success

contracts?array<ContractPnLPeriods>

One series per contract found.

Show attributes
contractId?string

The contract.

Format"byte" base64

periods?array<PnLPeriod>

The series, one entry per bucket across the range in time order, with zeroes for a bucket with no activity.

Show attributes
buyCostCents?string

Cost of items purchased during this period, in cents: the sum of listing_price_cents for purchases made in this time bucket.

Format"int64"

buyCostMicros?string

buy_cost_cents in millionths of a dollar, summed from the exact buy prices. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.

Format"int64"

lostCostCents?string

The buy cost of the items lost in this period, in cents, bucketed by when they were lost. Pnl_cents already subtracts it.

Format"int64"

lostCostMicros?string

lost_cost_cents in millionths of a dollar, from the exact buy prices.

Format"int64"

marketplaces?array<PnLPeriodMarketplace>

The period's realised profit split by selling marketplace, present only when the request set group_by_marketplace. The entries sum to pnl_cents. A sale whose marketplace is unknown is grouped as "unknown".

Show attributes
marketplace?string

The selling market that settled the sales. "unknown" when the sale predates selling_marketplace and cannot be attributed.

pnlCents?string

Realised profit for the items this market settled in the period, in cents: sell revenue minus the buy cost of those same sold items.

Format"int64"

pnlMicros?string

pnl_cents in millionths of a dollar, from the exact buy cost. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.

Format"int64"

periodEnd?string

End of this period's time bucket, inclusive.

Format"date-time"

periodStart?string

Start of this period's time bucket, inclusive.

Format"date-time"

pnlCents?string

Realised profit for items sold during this period, in cents: sell revenue minus buy cost for those same sold items, bucketed by sale completion time, minus the cost of the items lost in the period (lost_cost_cents), bucketed by when they were lost.

Format"int64"

pnlMicros?string

pnl_cents in millionths of a dollar: sell revenue minus the exact buy cost of those sold items and of the items lost in the period. Exact to the millionth of a dollar, so a purchase charged a fraction of a cent counts at what it cost. The _cents figure beside it sums prices rounded up to a cent and is kept for limits.

Format"int64"

purchaseCount?string

Number of purchases made during this period.

Format"int64"

saleCount?string

Number of items sold during this period, bucketed by sale completion time and credited to a contract as sell_revenue_cents is. Lost items are not sales and are not counted.

Format"int64"

sellRevenueCents?string

Realised sell revenue for items sold during this period, in cents: the sum of sell_price_cents for sales completed in this time bucket.

Format"int64"

strategies?array<PnLPeriodStrategy>

The period's purchases split by the buying mechanism that produced each one, present only when the request set group_purchases_by_strategy. The entries sum to purchase_count.

Show attributes
purchaseCount?string

Number of purchases this mechanism made during the period.

Format"int64"

strategy?string

The buying mechanism that produced the purchases.

Value in"PURCHASE_STRATEGY_LISTING""PURCHASE_STRATEGY_BUY_ORDER""PURCHASE_STRATEGY_AUCTION""PURCHASE_STRATEGY_OFFER"

curl -X POST "https://api.goldmine.to/contracts.v1.Contracts/GetContractPnLPeriods" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractIds": [
      "AY86PB0ufwCKGyw9Tl9gcQ=="
    ],
    "endTime": "2026-11-03T16:10:00Z",
    "granularity": "PNL_GRANULARITY_DAY",
    "startTime": "2026-11-03T16:10:00Z"
  }'
{
  "contracts": [
    {
      "contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
      "periods": [
        {}
      ]
    }
  ]
}