---
updatedAt: 2025-02-24T15:31:26.000Z
agentTools:
  projectIndex: https://documentation.safecube.ai/llms.txt
---

# Retrieve list of shipments called with the API

Retrieve the list of shipments called with the API within the provided timeframe, that usages have a minimum resolution of a month (you cant select the usage for one  week for example, the usage will automatically be for the month of the week provided)

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Webhook api",
    "version": "1.2.1",
    "description": "Welcome to the documentation of Webhook API\n<h1>Compatibility guidelines</h1> <p>The HTTP API is versioned with a single number, which is currently 1</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>/webhook/api/v1</strong> for the current version. <p>Please notice that all \"/shipment\" endpoints are deprecated. Therefore it is recommended to use the \"/easy-shipment\" endpoints.</p>\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 Ports and Vessels  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>1.2.0</h2> <ul> <li>POST /easy-shipment-asynchronous</li> </ul> <h2>1.1.0</h2> <ul> <li>Easy-shipment endpoints</li> </ul> <h2>1.0.0</h2> <ul> <li>Manage webhook</li> </ul>"
  },
  "servers": [
    {
      "url": "https://api.sinay.ai/webhook/api/v1"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Usages",
      "description": "Allow you to retrieve your usages of the API"
    }
  ],
  "paths": {
    "/shipment-usage": {
      "get": {
        "tags": [
          "Usages"
        ],
        "operationId": "retrieveShipmentUsages",
        "summary": "Retrieve list of shipments called with the API",
        "description": "Retrieve the list of shipments called with the API within the provided timeframe, that usages have a minimum resolution of a month (you cant select the usage for one  week for example, the usage will automatically be for the month of the week provided)",
        "parameters": [
          {
            "in": "query",
            "name": "startTime",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2024-06-12T12:00:00Z"
            },
            "description": "Start time at which usages must be found"
          },
          {
            "in": "query",
            "name": "endTime",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time",
              "example": "2024-06-12T12:00:00Z"
            },
            "description": "End time at which usages must be found"
          },
          {
            "in": "query",
            "name": "periodicity",
            "required": false,
            "schema": {
              "enum": [
                "DAILY",
                "MONTHLY"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage has been recovered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentCustomUsages"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpErrorOut"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpErrorOut"
                }
              }
            }
          },
          "500": {
            "description": "An error occurred on server side",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpErrorOut"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HttpErrorOut": {
        "title": "HttpError",
        "type": "object",
        "required": [
          "code",
          "detail"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        }
      },
      "ShipmentCustomUsages": {
        "type": "object",
        "properties": {
          "apis": {
            "$ref": "#/components/schemas/ShipmentCustomUsagesApis"
          }
        }
      },
      "ShipmentCustomUsagesApis": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/ShipmentCustomUsagesApi"
        }
      },
      "ShipmentCustomUsagesApi": {
        "type": "object",
        "properties": {
          "periodicUsages": {
            "$ref": "#/components/schemas/PeriodicCustomUsages"
          }
        }
      },
      "PeriodicCustomUsages": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/customUsage"
        }
      },
      "customUsage": {
        "type": "object",
        "required": [
          "consumedShipment",
          "consumedShipmentList"
        ],
        "properties": {
          "consumedShipment": {
            "type": "integer",
            "format": "int32"
          },
          "consumedShipmentList": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "API_KEY"
      }
    }
  }
}
```