Track Cargo

Get the current status of a submitted request.


GET /cargo/{cargo_id}/tracking

Authentication

This endpoint requires the X-API-Key header with a valid project API key.


-H "X-API-Key: convoy_sk_your_key_here"

Project Scoping: You can only track cargo that belongs to your project. Attempting to track cargo from another project returns 404 Not Found.

Path Parameters

Parameter	Type	Description
`cargo_id`	string	The cargo ID from `/cargo/load` response

Response


{
  "cargo_id": "crg_abc123def456",
  "status": "processing",
  "status_description": "Batch is being processed by the provider",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Field	Description
`cargo_id`	Request identifier
`status`	Current status (see below)
`status_description`	Human-readable status
`created_at`	When request was submitted
`updated_at`	Last status change

Status Values

Status	Description
`pending`	Waiting to be assigned to a batch
`batched`	Assigned to a batch job
`processing`	Batch is being processed
`completed`	Processing completed
`failed`	Processing failed
`callback_pending`	Result ready, delivering callback
`callback_delivered`	Callback sent successfully
`callback_failed`	Callback delivery failed

Examples

curl


curl -H "X-API-Key: convoy_sk_your_key_here" \
  https://api.cnvy.ai/cargo/crg_abc123def456/tracking

Python


import httpx
 
cargo_id = "crg_abc123def456"
response = httpx.get(
    f"https://api.cnvy.ai/cargo/{cargo_id}/tracking",
    headers={"X-API-Key": "convoy_sk_your_key_here"}
)
 
data = response.json()
print(f"Status: {data['status']}")
print(f"Description: {data['status_description']}")

Polling Example


import httpx
import time
 
def wait_for_completion(cargo_id: str, api_key: str, timeout: int = 3600) -> dict:
    """Poll until cargo is processed or timeout."""
    start = time.time()
    terminal_statuses = {"callback_delivered", "callback_failed", "failed"}
    
    while time.time() - start < timeout:
        response = httpx.get(
            f"https://api.cnvy.ai/cargo/{cargo_id}/tracking",
            headers={"X-API-Key": api_key}
        )
        data = response.json()
        
        if data["status"] in terminal_statuses:
            return data
        
        time.sleep(30)  # Poll every 30 seconds
    
    raise TimeoutError(f"Cargo {cargo_id} not completed in {timeout}s")
 
# Usage
result = wait_for_completion(
    "crg_abc123def456",
    "convoy_sk_your_key_here"
)

JavaScript


async function trackCargo(cargoId, apiKey) {
  const response = await fetch(
    `https://api.cnvy.ai/cargo/${cargoId}/tracking`,
    {
      headers: { "X-API-Key": apiKey }
    }
  );
  return response.json();
}
 
// Usage
const status = await trackCargo(
  "crg_abc123def456",
  "convoy_sk_your_key_here"
);
console.log(`Status: ${status.status}`);

Errors

Status	Description
`401`	Missing or invalid API key
`403`	Project is inactive
`404`	Cargo not found or not owned by your project
`500`	Internal server error

Error Response Examples


{"detail": "API key required. Include X-API-Key header."}


{"detail": "Cargo not found"}

A 404 response may mean the cargo doesn’t exist OR it belongs to a different project. This prevents information leakage about other projects’ cargo.