---
updatedAt: 2026-09-28T14:40:44.000Z
agentTools:
  projectIndex: https://documentation.safecube.ai/llms.txt
---

# Schedule API

## Overview

The Schedule API provides access to global shipping schedules from multiple shipping lines. Coverage is not universal — different carriers provide varying levels of schedule data. Users can retrieve schedules in three ways:

* **By Port → Port** (most frequent coverage, 79 shipping lines)
* **By Vessel** (46 shipping lines)
* **By Port** (24 shipping lines)

This document details which shipping lines are supported for each type of query.

[Coverage](schedule-api-coverage)

**Base URL**: <https://api.sinay.ai/schedule/api/v1>

***

## Getting started

Every request must be authenticated with your API key, passed in the `API_KEY` header, together with the standard HTTP headers.

```http
GET /schedule/api/v1/schedule/FRLEH HTTP/1.1
Host: api.sinay.ai
API_KEY: <your-api-key>
```

See [Mandatory Headers](https://documentation.safecube.ai/reference/mandatory-headers) for the full list of required HTTP headers.

A request with a missing, invalid or expired key — or a key without access to the Schedule product — is rejected (`401` / `403`) and **does not consume any credit**.

***

## How credits are counted

Access to the Schedule API is **credit-based**. The rule is simple:

> **You are charged 1 credit per schedule api call.**

### Good to know

* **Failed requests are free.** Authentication errors, malformed port codes, and quota-exceeded responses never consume credits.
* Schedule credits are a **dedicated credit type** and are independent from your other products (Shipment, Congestion, …).

***

## Quotas and rate limiting

Two independent protections can stop a request:

* **Credit quota reached** → `403 Forbidden`. The request is blocked *before* processing — no credit is consumed. Top up or wait for your next period.
* **Too many requests in a short window** → `429 Too Many Requests`. A maximum call rate of **10 requests per 10 seconds per API key** applies. Simply retry shortly after.

See [Rate Limit](https://documentation.safecube.ai/reference/rate-limit) for details.

***

## Tracking your consumption

To check your balance **without consuming a credit**:

```http
GET /schedule/api/v1/consumption/current-period
API_KEY: <your-api-key>
```

Typical fields returned:

| Field                       | Meaning                                      |
| --------------------------- | -------------------------------------------- |
| `creditsInitial`            | Credits allocated at the start of the period |
| `credits`                   | Remaining credits                            |
| `periodStart` / `periodEnd` | Start and end of the current period          |
| `expired`                   | Whether the period has expired               |

To retrieve the full history of your periods, use `/consumption/periods`.

See [Current consumption period](https://documentation.safecube.ai/reference/retrievecurrentconsumptionperiod-1) and [Consumption periods](https://documentation.safecube.ai/reference/retrieveconsumptionperiods-1).

***

## Error responses

All errors share a common body:

```json
{
  "errorCode": 404,
  "message": "unable to retrieve schedule",
  "details": [],
  "time": "2026-06-24T10:30:00Z"
}
```

| Status                      | Meaning                                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Invalid input (e.g. a port code that is not 5 alphanumeric characters)                         |
| `401 Unauthorized`          | Authentication failed                                                                          |
| `403 Forbidden`             | Usage limit reached                                                                            |
| `404 Not Found`             | No schedule data found for the requested resource                                              |
| `429 Too Many Requests`     | Rate limit exceeded — see [Rate Limit](https://documentation.safecube.ai/reference/rate-limit) |
| `500 Internal Server Error` | An error occurred on the server side                                                           |

<br />