Timesheet segments

Segmented Tracking breaks a shift into segments: where the employee clocked in, when they were driving, stopped at a job site, idle somewhere else or on a break, and where they clocked out. The segments endpoint returns those segments for one timesheet, along with a summary of the shift.

📘

Before you start

• Your company needs the Segmented Tracking add-on.
• Send your API key in the Authorization header, as with every Public API request.
• The timesheet must be clocked out. Segments for a shift still in progress aren't available.

Request

curl --request GET \
  --url https://api.timeero.app/api/public/segments/3018106 \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Accept: application/json'

timesheetId is the id of a timesheet, as returned by the timesheets endpoints.

How the request flow works

Segments are generated once and then stored. Most clocked-out timesheets already have them, so the first request usually returns them. When they haven't been generated yet, the API starts generating them in the background and asks you to come back.

🚧

One timesheet at a time

If you need segments for many timesheets, request them one after another: wait for a 200 on one before moving to the next. Requesting several at once only returns 429 for all but the first.

Polling example

async function getSegments(timesheetId, apiKey) {
  const url = `https://api.timeero.app/api/public/segments/${timesheetId}`;

  for (let attempt = 0; attempt < 30; attempt++) {
    const response = await fetch(url, {
      headers: { Authorization: apiKey, Accept: 'application/json' },
    });

    if (response.status === 200) {
      return (await response.json()).items;
    }

    // 202: still generating. 429: another timesheet is generating.
    if (response.status === 202 || response.status === 429) {
      await new Promise((resolve) => setTimeout(resolve, 10000));
      continue;
    }

    const body = await response.json();
    throw new Error(`${response.status}: ${body.message ?? body.error_message}`);
  }

  throw new Error('Segments were not ready in time. Try again later.');
}

Reading the response

A 200 response wraps the segments in items:

{
  "items": {
    "timesheet_id": 3018106,
    "job_name": "Riverside Office",
    "clock_in_time": "2026-10-27T08:00:12",
    "clock_out_time": "2026-10-27T10:05:40",
    "total_duration": 7528,
    "duration_human": "02h 05m",
    "total_break_duration": "15m",
    "driving_distance": 12.43,
    "mileage": 12.43,
    "segments": [ ... ]
  },
  "message": "Segments loaded successfully."
}

📘

Times and units

• Times are the employee's local time, in the format YYYY-MM-DDTHH:mm:ss, with no UTC offset.
• total_duration and duration_in_seconds are in seconds.
• driving_distance and mileage are always in miles. A driving segment's distance uses your company's unit (kilometers or miles), and distance_in_km and distance_in_miles give both.

Fields summary

Segment categories

Segment fields

Every segment has the same fields. Fields that don't apply to a category are null, or an empty array for breaks.

Breaks

Location

Site

Segments generated a long time ago may include fewer site fields.

Errors

Errors return an error_code and a message. Authentication errors use error_message instead of message.