Retrieve Planned Runs

Before you start

Run these examples on a trusted server with TAROT_API_KEY set in its environment. Use X-Tarot-API-Key on every request. Never expose the key in client-side code, including browser or mobile app code. See Getting an API key.

Plan in Tarot Routing

After creating your jobs, a planner selects the available drivers, optimises the scenario, and reviews the routes in Tarot Routing.

Ensure you have the scenario’s numeric ID, from POST /v3/core/jobs/bulk_create or GET /v3/core/scenarios. These examples assume it is available in the SCENARIO_ID environment variable.

Retrieve planned runs

Once planning is complete, retrieve the runs saved to the scenario:

GET /v3/core/runs?scenario_id={scenario_id}&page=1&per_page=100

curl --fail-with-body "https://api.optimiser.app/v3/core/runs?scenario_id=${SCENARIO_ID}&page=1&per_page=100" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY"

import os, requests

scenario_id = os.environ["SCENARIO_ID"]
response = requests.get(
    f"https://api.optimiser.app/v3/core/runs?scenario_id={scenario_id}&page=1&per_page=100",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.json())

const response = await fetch(`https://api.optimiser.app/v3/core/runs?scenario_id=${process.env.SCENARIO_ID}&page=1&per_page=100`, {
  headers: { "X-Tarot-API-Key": process.env.TAROT_API_KEY },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.json());

The response contains data, page, per_page, total_pages, and total_count. Process data and request subsequent pages through total_pages, preserving the scenario filter.

Each run has an id, driver information, and a jobs list ordered by seq. Jobs include their numeric id, your uid, and planned eta. See the RunSchema reference.

To include unassigned jobs in your review, also retrieve GET /v3/core/jobs?scenario_ids={scenario_id}&page=1&per_page=100. Jobs with no run_id remain unassigned.

Review and dispatch

Review the routes and any unassigned jobs, then dispatch from Tarot Routing using runsheet QR codes, email/SMS links, or driver-account assignments. Once deliveries begin, continue to Retrieve delivery proofs.