Skip to content

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.

POST/contracts.v1.Contracts/ListPnLByItem

Request body

application/jsonRequired

Request for one page of the caller's workspace profit grouped by item name, in the requested order.

cursor?string

Opaque pagination cursor from a previous ListPnLByItemResponse. Empty for the first page.

descending?boolean

Order descending instead of ascending.

filter?PnLByItemFilter

Optional filters and the period, applied before pagination. Keep unchanged when continuing with a cursor.

Show attributes
activity?string

Optional 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_BY_ITEM_ACTIVITY_BOUGHT""PNL_BY_ITEM_ACTIVITY_REALIZED"

contractId?string

Optional 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?string

Optional 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?string

Optional case-insensitive substring of the item name.

sign?string

Optional filter on the sign of the row's realised profit: PROFIT keeps rows at or above zero, LOSS rows below zero.

Value in"PROFIT_SIGN_PROFIT""PROFIT_SIGN_LOSS"

startTime?string

Optional 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?integer

Maximum number of rows to return. Server caps this at a service-defined upper bound.

Format"int32"

sortField?string

Aggregate to order the page by. Unspecified orders by item name. Keep the same sort and filter when continuing with a cursor.

Value in"PNL_BY_ITEM_SORT_FIELD_NAME""PNL_BY_ITEM_SORT_FIELD_ITEMS_SOLD""PNL_BY_ITEM_SORT_FIELD_REVENUE""PNL_BY_ITEM_SORT_FIELD_COST""PNL_BY_ITEM_SORT_FIELD_HOLDING_DURATION""PNL_BY_ITEM_SORT_FIELD_PNL""PNL_BY_ITEM_SORT_FIELD_MARGIN""PNL_BY_ITEM_SORT_FIELD_ITEMS_BOUGHT""PNL_BY_ITEM_SORT_FIELD_BUY_COST"

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?string

Mean time from delivery to sale over the sold items, rounded to whole seconds. Zero when nothing of this name sold in the period.

buyCostCents?string

Buy cost of those delivered items, in cents.

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"

heldCostCents?string

Buy cost of the items held now, in cents. Ignores the period like items_held.

Format"int64"

heldCostMicros?string

held_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?string

Number of items of this name delivered in the period.

Format"int64"

itemsHeld?string

Items 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?string

Number of items of this name sold in the period.

Format"int64"

marketHashName?string

The item name this row reports on.

pnlCents?string

Realised profit of the sold items, in cents: revenue_cents minus sold_cost_cents.

Format"int64"

pnlMicros?string

pnl_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?string

Realised sell revenue of those sold items, in cents.

Format"int64"

soldCostCents?string

Buy cost of those same sold items, in cents.

Format"int64"

soldCostMicros?string

sold_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?string

Cursor to pass to fetch the next page. Empty when there are no more results.

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"
  }'
{
  "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": ""
}