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.
/ contracts. v1. Contracts/ GetPnLPeriodsRequest body
application/jsonRequired
Request for the caller's workspace profit per day, week or month over a time range, optionally for one contract.
buyingMarketplace?stringOptional 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?stringOptional filter: scope the period series to one contract instead of the whole workspace.
Format"byte" base64
endTime?stringEnd of the period range. The request is rejected when left out.
Format"date-time"
granularity?stringTime 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_"PNL_"PNL_"PNL_
groupByMarketplace?booleanWhen true, each period also carries its realised profit split by selling marketplace in marketplaces.
groupPurchasesByStrategy?booleanWhen true, each period also carries its purchases split by buying mechanism in strategies.
startTime?stringStart 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?stringCost of items purchased during this period, in cents: the sum of listing_price_cents for purchases made in this time bucket.
Format"int64"
buyCostMicros?stringbuy_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?stringThe 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?stringlost_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?stringThe selling market that settled the sales. "unknown" when the sale predates selling_marketplace and cannot be attributed.
pnlCents?stringRealised 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?stringpnl_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?stringEnd of this period's time bucket, inclusive.
Format"date-time"
periodStart?stringStart of this period's time bucket, inclusive.
Format"date-time"
pnlCents?stringRealised 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?stringpnl_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?stringNumber of purchases made during this period.
Format"int64"
saleCount?stringNumber 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?stringRealised 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?stringNumber of purchases this mechanism made during the period.
Format"int64"
strategy?stringThe buying mechanism that produced the purchases.
Value in"PURCHASE_"PURCHASE_"PURCHASE_"PURCHASE_
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/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"
}'const res = await fetch("https://api.goldmine.to/contracts.v1.Contracts/GetPnLPeriods", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"startTime": "2026-04-01T00:00:00Z",
"endTime": "2026-06-30T23:59:59Z",
"granularity": "month"
}),
});
const data = await res.json();body := strings.NewReader(`{
"startTime": "2026-04-01T00:00:00Z",
"endTime": "2026-06-30T23:59:59Z",
"granularity": "month"
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/contracts.v1.Contracts/GetPnLPeriods", 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/GetPnLPeriods",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"startTime": "2026-04-01T00:00:00Z",
"endTime": "2026-06-30T23:59:59Z",
"granularity": "month"
},
)
data = res.json(){
"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"
}
]
}{
"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."
}