---
updatedAt: 2026-08-19T08:09:21.000Z
agentTools:
  projectIndex: https://documentation.safecube.ai/llms.txt
---

# Retrieve your monthly usages

<p>The endpoint allows you to retrieve your monthly usages of the API</p>

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "API Container Tracking",
    "version": "PROJECT_VERSION",
    "description": "Welcome to the documentation of the Container Tracking API\n<h1>Compatibility guidelines</h1> <p>The HTTP API is versioned with a single number, which is currently 2</p> <p>This number symbolizes the major version number. New features can be added to the API in the same version number if there is no breaking change.</p> <p>The version number is present in the url, for instance <strong>/container-tracking/api/v2</strong> for the current version.\n<h1>Documentation, Pricing and Key generation</h1> <p>You can find the complete documentation for our API at <a href='https://developers.sinay.ai/'>Developers Platform</a>.</p> <p>Create an account to receive your FREE key in under a minute!</p> <p>Additionally, explore our pricing plans, access support, view detailed documentation, and follow our comprehensive tutorials.</p>\n<h1>Authentication</h1> <p>Every endpoints of this API require authentication using an API key.</p> <p>If you don't have an API Key and you need to use the Container Tracking API, you need to ask Sinay to have one.</p> <p>To use the API Key, you must add a header named <strong>API_KEY</strong> with your API Key as a value.</p> <h1>Test the API with Swagger-ui</h1> <p>To test the API using Swagger-ui, you must click on the button <strong>Authorize</strong> and then fill the <strong>apiKey</strong> field and click on <strong>Authorize</strong>.</p> <p>Swagger-ui will then use the api key automatically in each request.</p> <p>On every endpoints, you can click on <strong>Try it out</strong>, you can modify the body and then click on <strong>Execute</strong></p> <p>You will be able to see the response.</p>\n<h1>Release note</h1> <h2>2.8.0</h2> <ul> <li>Add the /shipment-format/searates endpoint returning a Searates-compatible output, with an optional safecubeFields flag to expose SafeCube-specific fields</li> </ul> <h2>2.1.0</h2> <ul> <li>Fix null entries</li> </ul> <h2>2.0.2</h2> <ul> <li>Set route and ais fields as default true in shipment request parameters</li> </ul> <h2>2.0.0</h2> <ul> <li>Replace all existing tracking endpoints with a single one</li> <li>Add additional information such as: vessel, facilities or route segments</li> </ul> <h2>1.5.0</h2> <ul> <li>Default AUTO for Sealine with BL</li> </ul> <h2>1.4.0</h2> <ul> <li>Retrieve all events</li> </ul> <h2>1.3.0</h2> <ul> <li>Retrieve supported sealines</li> </ul> <h2>1.2.0</h2> <ul> <li>Retrieve container eta</li> <li>Retrieve eta for every container in BK or BL</li> </ul> <h2>1.1.0</h2> <ul> <li>Retrieve container location</li> <li>Retrieve location for every container in BK or BL</li> </ul> <h2>1.0.0</h2> <ul> <li>Retrieve Container Status</li> <li>Retrieve status for every container in BK or BL</li> </ul>"
  },
  "servers": [
    {
      "url": "api.sinay.ai/container-tracking/api/v2"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Usage",
      "description": "Endpoint that allows you to retrieve information about your usage"
    }
  ],
  "paths": {
    "/usages": {
      "get": {
        "parameters": [
          {
            "$ref": "#/components/parameters/usageStartTime"
          },
          {
            "$ref": "#/components/parameters/usageEndTime"
          }
        ],
        "operationId": "retrieveUsages",
        "summary": "Retrieve your monthly usages",
        "description": "<p>The endpoint allows you to retrieve your monthly usages of the API</p>",
        "tags": [
          "Usage"
        ],
        "responses": {
          "200": {
            "description": "The monthly usages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/usagesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/internalServerError"
          },
          "default": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "API_KEY"
      }
    },
    "parameters": {
      "usageStartTime": {
        "in": "query",
        "name": "startTime",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Start time at which usages must be found"
      },
      "usageEndTime": {
        "in": "query",
        "name": "endTime",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "End time at which usages must be found"
      }
    },
    "schemas": {
      "errorInfo": {
        "type": "object",
        "required": [
          "errorCode",
          "message",
          "details",
          "time"
        ],
        "properties": {
          "errorCode": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "time": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "numberOfCalls": {
        "type": "integer",
        "format": "int64"
      },
      "periodicUsage": {
        "type": "object",
        "required": [
          "allCalls",
          "successCalls",
          "clientErrorCalls",
          "serverErrorCalls",
          "consumedApiUnits"
        ],
        "properties": {
          "allCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "successCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "clientErrorCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "serverErrorCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "consumedApiUnits": {
            "$ref": "#/components/schemas/numberOfCalls"
          }
        }
      },
      "periodicUsages": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/periodicUsage"
        }
      },
      "usagesResponse": {
        "type": "object",
        "required": [
          "allCalls",
          "successCalls",
          "clientErrorCalls",
          "serverErrorCalls",
          "consumedApiUnits"
        ],
        "properties": {
          "allCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "successCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "clientErrorCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "serverErrorCalls": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "consumedApiUnits": {
            "$ref": "#/components/schemas/numberOfCalls"
          },
          "periodicUsages": {
            "$ref": "#/components/schemas/periodicUsages"
          }
        },
        "example": {
          "allCalls": 15,
          "successCalls": 13,
          "clientErrorCalls": 1,
          "serverErrorCalls": 1,
          "consumedApiUnits": 25,
          "periodicUsages": {
            "2022-05": {
              "allCalls": 15,
              "successCalls": 13,
              "clientErrorCalls": 1,
              "serverErrorCalls": 1,
              "consumedApiUnits": 25
            }
          }
        }
      }
    },
    "responses": {
      "default": {
        "description": "default",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorInfo"
            }
          }
        }
      },
      "unauthorized": {
        "description": "The authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorInfo"
            }
          }
        }
      },
      "internalServerError": {
        "description": "An error occurred on server side",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/errorInfo"
            }
          }
        }
      }
    }
  }
}
```