Monitor your credit consumption

Your API key comes with credits, grouped into periods (for example, one period per month of your subscription). Use the /consumption endpoints to:

see how many credits you have left,
list your periods,
for shipment credits, list the shipments that used a credit in a period.

Endpoints

Method	Path	Returns
`GET`	`/consumption/current-period`	The current period
`GET`	`/consumption/current-period/shipments`	The shipments consumed in the current period
`GET`	`/consumption/periods`	All your periods
`GET`	`/consumption/periods/{periodId}`	One period
`GET`	`/consumption/periods/{periodId}/shipments`	The shipments consumed in one period

Add these paths to the base URL of the API:

API	Base URL	Credit type	`/shipments`
Container Tracking	`https://api.sinay.ai/container-tracking/api/v2`	Shipment	Yes
Webhook	`https://api.sinay.ai/webhook/api/v1`	Shipment	Yes
Safecube	`https://api.sinay.ai/safecube/api/v1`	Shipment	Yes
Congestion	`https://api.sinay.ai/congestion/api/v1`	Congestion	No

Container Tracking, Webhook and Safecube use the same shipment credits. Their /consumption endpoints return the same periods and the same shipments.

Authentication

Authenticate with your API key in the API_KEY header, as for any other call.

API_KEY: <your_api_key>

You only see the credits of the key you send.

Current period

Returns the period that is active now.

curl "https://api.sinay.ai/container-tracking/api/v2/consumption/current-period" \
  -H "API_KEY: <your_api_key>"

{
  "id": "3f6c1b2e-8a4d-4c7e-9f21-5b0d6a7e9c13",
  "credits": 412,
  "creditsInitial": 500,
  "validityDateBegin": "2026-10-01T00:00:00Z",
  "validityDateEnd": "2026-10-31T23:59:59Z",
  "expired": false
}

All periods

Returns all the periods of your key: past, current, and upcoming.

curl "https://api.sinay.ai/container-tracking/api/v2/consumption/periods" \
  -H "API_KEY: <your_api_key>"

{
  "periods": [
    {
      "id": "3f6c1b2e-8a4d-4c7e-9f21-5b0d6a7e9c13",
      "credits": 412,
      "creditsInitial": 500,
      "validityDateBegin": "2026-10-01T00:00:00Z",
      "validityDateEnd": "2026-10-31T23:59:59Z",
      "expired": false
    },
    {
      "id": "a91d0c47-2e3b-4f58-b6a0-7c2e4d1f8b95",
      "credits": 0,
      "creditsInitial": 500,
      "validityDateBegin": "2026-09-01T00:00:00Z",
      "validityDateEnd": "2026-09-30T23:59:59Z",
      "expired": true
    }
  ]
}

One period

Returns one period, using an id from /consumption/periods. The response has the same format as /consumption/current-period.

curl "https://api.sinay.ai/container-tracking/api/v2/consumption/periods/a91d0c47-2e3b-4f58-b6a0-7c2e4d1f8b95" \
  -H "API_KEY: <your_api_key>"

Period fields

Field	Type	Description
`id`	UUID	ID of the period
`credits`	integer	Credits left in the period
`creditsInitial`	integer	Credits available at the start of the period
`validityDateBegin`	date-time (UTC)	Start of the period
`validityDateEnd`	date-time (UTC)	End of the period
`expired`	boolean	`true` if the period is over or was ended early

Credits used in the period = creditsInitial − credits.

Shipments consumed in a period

Returns the shipments that used a credit in a period, with the date each one was first tracked in that period. Only available for shipment credits (Container Tracking, Webhook, Safecube).

Current period

curl "https://api.sinay.ai/container-tracking/api/v2/consumption/current-period/shipments" \
  -H "API_KEY: <your_api_key>"

A given period, page 2 with 50 results per page

curl -G "https://api.sinay.ai/container-tracking/api/v2/consumption/periods/a91d0c47-2e3b-4f58-b6a0-7c2e4d1f8b95/shipments" \
  -H "API_KEY: <your_api_key>" \
  --data-urlencode "page=1" \
  --data-urlencode "size=50"

Query parameters

Name	Type	Description	Default
`page`	integer ≥ 0	Page number, starting at `0`	`0`
`size`	integer from 1 to 500	Number of results per page. Values above 500 are reduced to 500	`100`

An invalid page or size (not a number, or below the minimum) returns 400.

Response

{
  "consumedShipments": [
    {
      "purchaseObject": "EMCU1686335",
      "createdAt": "2026-10-07T13:13:44Z"
    },
    {
      "purchaseObject": "WBPU7087049",
      "createdAt": "2026-10-06T14:43:57Z"
    }
  ],
  "page": 0,
  "size": 100,
  "totalElements": 2
}

Field	Type	Description
`consumedShipments[].purchaseObject`	string	Shipment that used a credit (container number, booking or B/L number)
`consumedShipments[].createdAt`	date-time (UTC)	When the shipment used its credit in this period
`page`	integer	Current page number
`size`	integer	Page size
`totalElements`	integer	Total number of shipments consumed in the period

Errors

Status	When
`400`	`page` or `size` is invalid
`401`	`API_KEY` is missing or invalid
`404`	Unknown path, unknown `periodId` for your key, no current period, or `/shipments` called on an API without shipment credits
`429`	Rate limit reached

How credits are consumed

Shipment credits (Container Tracking, Webhook, Safecube): a credit is used the first time a shipment is tracked in a period. Tracking the same shipment again in the same period uses no extra credit. Calls that return 2xx, 404 or 503 count; other errors don't.
Congestion and Schedule credits: only successful calls (2xx) use credits.
On an unlimited plan, credits can go below zero. It then shows how much you used beyond the initial amount.

Good to know

Rate limit: up to 10 calls every 10 seconds on /consumption.
Calls to /consumption are free: they use no credits and don't appear in your /logs.
Calls per day or month: use /shipment-usage (Container Tracking, Webhook, Safecube) to get the shipments called per day or per month, independently of your credit periods.