Skip to content

API Reference / Profit

Get profit over time periods

Returns a workspace's profit bucketed into day, week, or month periods across a time range, for plotting trends. Optionally scoped to a single contract.

POST/contracts.v1.Contracts/GetPnLPeriods

Request body

application/jsonRequired

Request for the caller's workspace profit per day, week or month over a time range, optionally for one contract.

buyingMarketplace?string

Optional filter: scope the series to items bought on this marketplace: purchases made on it (buy_cost, purchase_count, on the paid time) and sales of items bought on it. Unset covers every marketplace.

contractId?string

Optional filter: scope the period series to one contract instead of the whole workspace.

Format"byte" base64

endTime?string

End of the period range. The request is rejected when left out.

Format"date-time"

granularity?string

Time bucket size for the series. The request is rejected when left out. HOUR is accepted only for a range of at most two days.

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

groupByMarketplace?boolean

When true, each period also carries its realised profit split by selling marketplace in marketplaces.

groupPurchasesByStrategy?boolean

When true, each period also carries its purchases split by buying mechanism in strategies.

startTime?string

Start of the period range. The request is rejected when left out.

Format"date-time"

Response body

application/json

Success

periods?array<PnLPeriod>

The profit time series, one entry per bucket across the requested range.

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/GetPnLPeriods" \
  -H "Authorization: Bearer $CSTRADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-04-01T00:00:00Z",
    "endTime": "2026-06-30T23:59:59Z",
    "granularity": "month"
  }'
{
  "periods": [
    {
      "periodStart": "2026-04-01T00:00:00Z",
      "periodEnd": "2026-04-30T23:59:59Z",
      "buyCostCents": "420000",
      "sellRevenueCents": "510000",
      "pnlCents": "90000",
      "purchaseCount": "104"
    },
    {
      "periodStart": "2026-05-01T00:00:00Z",
      "periodEnd": "2026-05-31T23:59:59Z",
      "buyCostCents": "380000",
      "sellRevenueCents": "445000",
      "pnlCents": "65000",
      "purchaseCount": "96"
    }
  ]
}