Skip to content

Tacho API

Read your company's data from Tacho in your own tools: a website that lists your drivers, a sheet of this month's jobs, a bot of your own. The API only reads, and a key only ever reads its own company.

Get a key

The owner of a company makes keys in the company admin, on the API tab. Make one key per tool and name it after where it goes. The key is shown once: Tacho keeps only a fingerprint of it, so copy it then. Revoking a key there stops it at once.

Managers see which keys exist and when each was last used. A key stops working when its company is deleted, and while whoever made it is banned from Tacho.

Your first request

Send the key in the Authorization header of every request. The address of the API is https://tacho.awesomecore.nl/api/v1.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://tacho.awesomecore.nl/api/v1/company
Answer
{
  "id": "cm3w9x1y20000abcd1234efgh",
  "name": "Nordic Haulage",
  "slug": "nordic-haulage",
  "tag": "NH",
  "logoUrl": null,
  "url": "https://tacho.awesomecore.nl/vtc/nordic-haulage",
  "verified": true,
  "truckersmpVtcId": 12345,
  "createdAt": "2026-11-13T18:02:11.000Z",
  "members": 3,
  "totals": {
    "allTime": { "km": 53925, "jobs": 118 },
    "thisMonth": { "month": "2026-11", "km": 6230, "jobs": 14 }
  }
}

Endpoints

All of them are GET and answer JSON. Distances are kilometres, money is in the game's currency (EUR for ETS2, USD for ATS) and times are ISO 8601 in UTC.

  • GET /api/v1/company

    Your company: name, tag, links, member count, and distance and jobs this month and all time.

  • GET /api/v1/members

    Active members: driver id, name, Discord and Steam ids, role, rank, when they joined, and what they delivered for the company.

  • GET /api/v1/jobs

    Every job of the company, newest first, a page at a time. The same fields as the jobs export.

  • GET /api/v1/jobs/{id}

    One job.

  • GET /api/v1/stats

    This month and all time: distance, jobs, drivers, income, fuel, games, and the last 12 months and top routes.

  • GET /api/v1/events

    Upcoming convoys the company runs, from TruckersMP and from a verified TrucklineMP VTC.

Only delivered jobs count in totals, ranks and stats, like everywhere on Tacho. Members are the ones your managers see in the admin. Each driver's Discord and Steam ids come along (null when not linked), so you can match them to your Discord server or TruckersMP. The API never gives out e-mail addresses or anything about other companies.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://tacho.awesomecore.nl/api/v1/members
Answer
{
  "rankMetric": "km",
  "members": [
    {
      "driverId": "cm3w9x1y20002abcd1234mnop",
      "name": "Kasper",
      "discordId": "238746823648726016",
      "steamId64": "76561198000000001",
      "role": "owner",
      "rank": { "id": "cm3w9x1y20005abcd1234qrst", "name": "Legend" },
      "joinedAt": "2026-11-13T18:02:11.000Z",
      "totals": { "km": 24310, "jobs": 51 }
    },
    {
      "driverId": "cm3w9x1y20003abcd1234uvwx",
      "name": "Ingrid",
      "discordId": null,
      "steamId64": "76561198000000002",
      "role": "manager",
      "rank": null,
      "joinedAt": "2026-11-14T09:30:00.000Z",
      "totals": { "km": 0, "jobs": 0 }
    }
  ]
}

Paging through jobs

/jobs gives a page of jobs, newest first, and nextCursor. Ask again with cursor set to it for the next page, until nextCursor is null. Pages stay right while new jobs come in.

ParameterWhat it does
limitJobs per page, 1 to 100. 50 when left out.
cursornextCursor from the page before, to get the next page.
sinceOnly jobs finished at or after this time (ISO 8601).
untilOnly jobs finished before this time.
driverOnly this driver's jobs (a driverId from /members).
statusdelivered, cancelled, flagged or rejected. Every status when left out.
gameets2 or ats.
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://tacho.awesomecore.nl/api/v1/jobs?status=delivered&since=2026-11-01T00:00:00Z&limit=100"
Answer
{
  "jobs": [
    {
      "id": "cm3wa0b9c0001abcd5678ijkl",
      "finishedAt": "2026-11-18T19:04:05.000Z",
      "startedAt": "2026-11-18T17:12:40.000Z",
      "driver": "Kasper",
      "driverId": "cm3w9x1y20002abcd1234mnop",
      "driverDiscordId": "238746823648726016",
      "driverSteamId64": "76561198000000001",
      "game": "ets2",
      "multiplayer": true,
      "promods": false,
      "kind": "cargo",
      "cargo": "Electronics",
      "cargoMassKg": 18400,
      "passengers": null,
      "source": { "city": "Hamburg", "company": "Krone Logistics" },
      "destination": { "city": "Lyon", "company": "TREE-ET" },
      "drivenKm": 1201.4,
      "plannedKm": 1196,
      "income": 52400,
      "revenue": 52400,
      "currency": "EUR",
      "fuelUsedL": 384.2,
      "damagePct": 1.2,
      "status": "delivered",
      "flagReasons": []
    }
  ],
  "nextCursor": "MTc2MzQ5MjY0NTAwMC5jbTN3YTBiOWMwMDAx"
}

Every page in a loop, in JavaScript (Node 18 or newer):

const KEY = process.env.TACHO_API_KEY;
const jobs = [];
let cursor = null;
do {
  const url = new URL("https://tacho.awesomecore.nl/api/v1/jobs");
  url.searchParams.set("since", "2026-11-01T00:00:00Z");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, wait * 1000));
    continue;
  }
  if (!res.ok) throw new Error((await res.json()).error.code);
  const page = await res.json();
  jobs.push(...page.jobs);
  cursor = page.nextCursor;
} while (cursor);

Errors

Errors are JSON with a code that stays the same and a message for people that may change. Check the code.

{
  "error": {
    "code": "invalid_key",
    "message": "That API key is wrong or was revoked."
  }
}
StatusCode
401missing_key

No Authorization header, or not a Bearer one.

401invalid_key

The key is wrong or was revoked.

400bad_request

A query parameter isn't right; details says which.

404not_found

No such endpoint, or no such job in your company.

405method_not_allowed

Only GET: the API only reads.

429rate_limited

Too many requests. Wait Retry-After seconds.

500internal_error

Something broke on Tacho's side. Try again.

Limits

Each key can make 60 requests a minute, unless Tacho raised it for that key; X-RateLimit-Limit says how many. Every answer says how many are left in X-RateLimit-Remaining, and when the minute is over in X-RateLimit-Reset (Unix seconds). Over the limit you get 429 with Retry-After: wait that many seconds. A tool that needs more can ask the people who run Tacho.

Totals and stats don't change from one second to the next. Ask every few minutes and keep the answer, rather than on every visit to your site.

Keep the key on a server

Anyone who has a key can read your company's data with it. Don't put it in a web page or an app you hand out: everyone who opens it can read the key. The API doesn't answer requests from web pages on other sites (no CORS) for that reason. Call it from your own server or bot and pass on what you need.

OpenAPI

Every endpoint and field is described in an OpenAPI 3.1 document. Open it in Postman, Insomnia or Bruno, or generate a client from it.

https://tacho.awesomecore.nl/api/v1/openapi.json

Hear about deliveries as they happen

The API answers when you ask. To be told the moment a job is delivered, a driver ranks up or a member joins, use webhooks: the owner sets them up in the company admin, under Settings.