Batch tracking
Submit a task for multiple numbers and retrieve its results
Batch tracking lets you submit multiple numbers in one request and retrieve the results for all of them in a separate request. Submit between 1 and 500 numbers with POST /v2/tracking/batch. The API returns a task_id without waiting for tracking results. Use this ID to retrieve the results in a separate request.
After a short wait, call GET /v2/tracking/batch?task_id=... with the same API key. The data.status field indicates the task state:
| Status | Meaning |
|---|---|
CREATED | The task is queued for processing. |
HANDLING | Processing is in progress. Request the results again later. |
PROCESSED | Processing is complete. Results are available in data.results. |
Once the task reaches PROCESSED, it is complete. You can stop requesting its status. Use tracking requests or webhooks for later shipment updates. Results are cached for up to 6 hours. Save them when the task finishes.
Each number has its own result: OK, INFO_NOT_FOUND, LINE_IS_UNDER_MAINTENANCE, LINE_NO_RESPONSE, or UNEXPECTED_ERROR. Missing data or a failure for one number does not cancel the other items.
company=AUTO is available only for type=container. For bills of lading and bookings, use a carrier SCAC code from the companies endpoint.
Request example
The example submits two numbers, checks the task at intervals, and prints each result. It limits the number of attempts so the program does not wait indefinitely.
// Create a task, wait for completion, and print each number’s result.
// Set the API URL and request parameters.
const API_BASE = "https://tracking.timetocargo.com/v2";
// 1. Submit the numbers and receive a task_id.
const created = await fetch(`${API_BASE}/tracking/batch?api_key=YOUR_TOKEN`, {
method: "POST",
headers: { Accept: "application/json", "Content-Type": "application/json" },
body: JSON.stringify({
tracked_items: [
{ company: "AUTO", track_number: { value: "MSDU8368827", type: "container" } },
{ company: "AUTO", track_number: { value: "CSNU6184414", type: "container" } },
],
}),
});
if (!created.ok) throw new Error(`HTTP ${created.status}`);
const createdBody = await created.json();
if (createdBody.status !== "OK") throw new Error(createdBody.status_description ?? createdBody.status);
let task;
// 2. Request the task state at intervals until it is complete.
for (let attempt = 0; attempt < 40; attempt += 1) {
const res = await fetch(`${API_BASE}/tracking/batch?api_key=YOUR_TOKEN&task_id=${createdBody.data.task_id}`, {
headers: { Accept: "application/json" },
});
// Check the HTTP response before using the result.
if (!res.ok) throw new Error(`HTTP ${res.status}`);
// Read JSON; success and status describe the request result.
const body = await res.json();
if (body.status !== "OK") throw new Error(body.status_description ?? body.status);
task = body.data;
if (task.status === "PROCESSED") break;
await new Promise((resolve) => setTimeout(resolve, 3000));
}
if (task.status !== "PROCESSED") throw new Error(`Task ${createdBody.data.task_id} is still ${task.status}`);
for (const item of task.results ?? []) {
const track = item.request?.track_number;
console.log(track?.value, item.status, item.status === "OK" ? item.data?.shipment_status : item.status_description);
}For HTTP status and API result handling, see Error handling.
Last updated on