API Reference / Profit
List profit by item
Returns one page of the workspace's profit grouped by item name over a period: items sold, revenue, cost, mean holding time and realised profit on the sold side, and items bought with their cost on the bought side. Optionally scoped to one contract and filtered by name or profit sign.
/ contracts. v1. Contracts/ ListPnLByItemRequest body
application/jsonRequired
Request for one page of the caller's workspace profit grouped by item name, in the requested order.
cursor?stringOpaque pagination cursor from a previous ListPnLByItemResponse. Empty for the first page.
descending?booleanOrder descending instead of ascending.
filter?PnLByItemFilterOptional filters and the period, applied before pagination. Keep unchanged when continuing with a cursor.
Show attributes
activity?stringOptional filter: BOUGHT keeps only names with an item bought in the period, REALIZED only names with an item sold or lost in the period, so a contract's purchases by item or its profit by item each count only their own side.
Value in"PNL_"PNL_
contractId?stringOptional filter: the bought and held sides count only items this contract bought. The sold and lost side counts the items credited to it as their buying or selling contract, as GetPnLBreakdown and GetPnLPeriods credit them, so a contract's rows sum to its own figures.
Format"byte" base64
endTime?stringOptional end of the period, exclusive. Lifetime when absent.
Format"date-time"
marketHashNames?array<string>Exact item names, OR within the field, so an item page reads its own row, or a page of catalog items reads theirs in one call. Empty includes every item. At most 200 names.
query?stringOptional case-insensitive substring of the item name.
sign?stringOptional filter on the sign of the row's realised profit: PROFIT keeps rows at or above zero, LOSS rows below zero.
Value in"PROFIT_"PROFIT_
startTime?stringOptional start of the period, inclusive. Sold items are windowed on sale completion time and bought items on delivery time. Lifetime when absent.
Format"date-time"
limit?integerMaximum number of rows to return. Server caps this at a service-defined upper bound.
Format"int32"
sortField?stringAggregate to order the page by. Unspecified orders by item name. Keep the same sort and filter when continuing with a cursor.
Value in"PNL_"PNL_"PNL_"PNL_"PNL_"PNL_"PNL_"PNL_"PNL_
Response body
application/json
Success
items?array<PnLByItem>One row per item name with any sale or delivery in the period, plus, when no period is set, any item held now, in the requested order.
Show attributes
averageHoldingDuration?stringMean time from delivery to sale over the sold items, rounded to whole seconds. Zero when nothing of this name sold in the period.
buyCostCents?stringBuy cost of those delivered items, in cents.
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"
heldCostCents?stringBuy cost of the items held now, in cents. Ignores the period like items_held.
Format"int64"
heldCostMicros?stringheld_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"
itemsBought?stringNumber of items of this name delivered in the period.
Format"int64"
itemsHeld?stringItems of this name the workspace holds now: arriving, in the inventory or listed. An as-of-now figure that ignores the period.
Format"int64"
itemsSold?stringNumber of items of this name sold in the period.
Format"int64"
marketHashName?stringThe item name this row reports on.
pnlCents?stringRealised profit of the sold items, in cents: revenue_cents minus sold_cost_cents.
Format"int64"
pnlMicros?stringpnl_cents in millionths of a dollar: revenue_cents times 10,000 minus sold_cost_micros. 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"
revenueCents?stringRealised sell revenue of those sold items, in cents.
Format"int64"
soldCostCents?stringBuy cost of those same sold items, in cents.
Format"int64"
soldCostMicros?stringsold_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"
nextCursor?stringCursor to pass to fetch the next page. Empty when there are no more results.
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/ListPnLByItem" \
-H "Authorization: Bearer $CSTRADER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cursor": "",
"descending": false,
"filter": {
"activity": "PNL_BY_ITEM_ACTIVITY_BOUGHT",
"contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
"endTime": "2026-11-03T16:10:00Z",
"marketHashNames": [
"AK-47 | Redline (Field-Tested)"
],
"query": "example",
"sign": "PROFIT_SIGN_PROFIT",
"startTime": "2026-11-03T16:10:00Z"
},
"limit": 50,
"sortField": "PNL_BY_ITEM_SORT_FIELD_NAME"
}'const res = await fetch("https://api.goldmine.to/contracts.v1.Contracts/ListPnLByItem", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CSTRADER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"cursor": "",
"descending": false,
"filter": {
"activity": "PNL_BY_ITEM_ACTIVITY_BOUGHT",
"contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
"endTime": "2026-11-03T16:10:00Z",
"marketHashNames": [
"AK-47 | Redline (Field-Tested)"
],
"query": "example",
"sign": "PROFIT_SIGN_PROFIT",
"startTime": "2026-11-03T16:10:00Z"
},
"limit": 50,
"sortField": "PNL_BY_ITEM_SORT_FIELD_NAME"
}),
});
const data = await res.json();body := strings.NewReader(`{
"cursor": "",
"descending": false,
"filter": {
"activity": "PNL_BY_ITEM_ACTIVITY_BOUGHT",
"contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
"endTime": "2026-11-03T16:10:00Z",
"marketHashNames": [
"AK-47 | Redline (Field-Tested)"
],
"query": "example",
"sign": "PROFIT_SIGN_PROFIT",
"startTime": "2026-11-03T16:10:00Z"
},
"limit": 50,
"sortField": "PNL_BY_ITEM_SORT_FIELD_NAME"
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.goldmine.to/contracts.v1.Contracts/ListPnLByItem", 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/ListPnLByItem",
headers={"Authorization": f"Bearer {os.environ['CSTRADER_API_KEY']}"},
json={
"cursor": "",
"descending": false,
"filter": {
"activity": "PNL_BY_ITEM_ACTIVITY_BOUGHT",
"contractId": "AY86PB0ufwCKGyw9Tl9gcQ==",
"endTime": "2026-11-03T16:10:00Z",
"marketHashNames": [
"AK-47 | Redline (Field-Tested)"
],
"query": "example",
"sign": "PROFIT_SIGN_PROFIT",
"startTime": "2026-11-03T16:10:00Z"
},
"limit": 50,
"sortField": "PNL_BY_ITEM_SORT_FIELD_NAME"
},
)
data = res.json(){
"items": [
{
"averageHoldingDuration": "example",
"buyCostCents": "2360",
"buyCostMicros": "2360",
"heldCostCents": "2360",
"heldCostMicros": "2360",
"itemsBought": "3",
"itemsHeld": "3",
"itemsSold": "3",
"marketHashName": "AK-47 | Redline (Field-Tested)",
"pnlCents": "2360",
"pnlMicros": "3",
"revenueCents": "2360",
"soldCostCents": "2360",
"soldCostMicros": "2360"
}
],
"nextCursor": ""
}{
"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."
}