# Get Timesheets

> GET /v1/timekeeping/timesheet

`GET https://app.untetherlabs.com/api/v1/timekeeping/timesheet`

Allows reading computed timesheet data for one or more providers.

Timesheets are returned for any matching provider who was active during the
specified date range even if they worked zero hours. These values are impacted
by historical corrections, you are advised to review the [Historical 
Corrections](/using-the-api/historical-corrections) documentation.

<ResponseField name="Available Expansions">
<Expandable title="expand options">
    * **provider**: Includes the entire provider object for each timesheet.
    * **paySegments**: Pay segments describe each individually worked span
        during the timesheet. They are the primitive unit of timekeeping data.
    * **scheduledPaySegments**: Scheduled pay segments represent the expected
        set of worked segments based on the schedule only, not punch data.
    * **problems**: Includes any warnings and errors for the timesheet.
    * **approval**: Includes whether the entire range is approved, and the
        exact sub ranges that have been approved.
    * **signOff**: Includes whether the entire range is signed off, and the
        exact sub ranges that have been signed off.
    * **historicalCorrections**: Includes any historical corrections which
        are applied to the time range of the timesheet. These are historical
        corrections which were made _to_ this time range as opposed to applied
        to/paid out in this range.
    * **totals**: The computed totals broken down by pay code and role for the
        requested range.
    * **historicalCorrectionTotals**: The totals from any historical corrections
        which are applied _to_ this timesheet (as opposed to corrections made
        to this timesheet). Historical correction totals are only available
        when requesting a particular pay period (by offset or exact reference).
</Expandable>
</ResponseField>

<Warning>
    This endpoint may have to do significant computation to generate timesheet data on-the-fly,
    you are advised to set appropriate timeout and consider caching the results if applicable.
</Warning>

This endpoint is paginated. See /using-the-api/pagination.

## Request

```bash
curl -X GET 'https://app.untetherlabs.com/api/v1/timekeeping/timesheet' \
  -H 'Authorization: Bearer $UNTETHER_API_KEY'
```

## Query parameters

- `teamId` (uuid)
- `providerId` (uuid)
- `payPeriodId` (uuid)
- `payPeriodOffset` (integer) — Optional offset from current pay period. 0 = current, 1 = next, -1 = previous.
- `startDate` (string, example "2024-11-20T07:43:34+0000")
- `endDate` (string, example "2024-11-20T07:43:34+0000")
- `expand` (string) — Available expansions: `provider`, `paySegments`, `scheduledPaySegments`, `problems`, `approval`, `signOff`, `historicalCorrections`, `totals`, `historicalCorrectionTotals` See [Query Parameters](/using-the-api/query-parameters) for more information on expansions.
- `pageSize` (number, default 20, min 1, max 200)
- `cursor` (string)

## Response 200

- `items` (Timesheet[], required)
  - `providerId` (uuid, required)
  - `provider` (Provider)
    - `name` (string | null, required, example "Bruce Wayne")
    - `email` (string, required, example "bruce.wayne@goodhealth.com")
    - `hireDate` (string | null, required, example "2024-11-20T07:43:34+0000")
    - `status` (enum, required, example "active", one of `onboarding`, `active`, `dismissed`, `unmanaged`)
    - `teamId` (uuid | null, required)
    - `licensedRegions` (string[], required)
    - `employmentType` (uuid | null, required)
  - `startDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `endDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `payPeriodId` (uuid | null, required) — The matching pay period, or null if the range does not align to a single pay period.
  - `scheduledShifts` (Shift[], required)
    - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
    - `version` (number) — Version number for optimistic locking. Include this when updating to detect conflicts.
    - `provider` (uuid | null, required) — The provider of the shift. If null, the shift is an open shift.
    - `providerName` (string | null) — The display name of the provider. Only populated when the request opts in via includeDisplayNames.
    - `startDate` (string, required, example "2024-11-20T07:43:34+0000")
    - `endDate` (string, required, example "2024-11-20T07:43:34+0000")
    - `segments` (ShiftSegment[], required) — The segments that make up a shift, ordered by startDate.
      - `importedId` (string | null, required) — If a segment was created in an external system, this is the ID of the segment in that system.
      - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
      - `role` (uuid | null, required) — The role of the shift. Can be null if the shift is pulled from an external system.
      - `roleName` (string | null) — The display name of the segment's role. Only populated when the request opts in via includeDisplayNames.
      - `roleColor` (string | null) — The hex color of the segment's role. Only populated when the request opts in via includeDisplayNames.
      - `roleImportedId` (string) — *DEPRECATED* The ID of the role in the external system. Once all roles are migrated to the system, this field will be removed.
      - `additionalInfo` (any) — *DEPRECATED* Additional information about the segment.
      - `isBreak` (boolean, required, example false) — Used to denote whether or not the provider will be on break during this segment.
      - `isOnCall` (boolean, required, example false)
      - `type` (enum, required, one of `working`, `paid_break`, `unpaid_break`, `on_call`) — The type of the segment.
      - `startDate` (string, required, example "2024-11-20T07:43:34+0000") — The timestamp of when the shift starts.
      - `endDate` (string, required, example "2024-11-20T07:43:34+0000") — The timestamp of when the shift ends.
      - `skillRequirement` (NullableSkillRequirement)
      - `labels` (string[], required) — The label IDs associated with this shift segment.
    - `payCodes` (ShiftPayCode[], max items 1)
      - `payCodeId` (uuid, required) — The pay code ID associated with this shift.
      - `value` (number) — Only present for variable pay codes. The value of the pay code for this shift.
    - `team` (uuid | null, required) — The team that the shift is associated with.
    - `note` (string | null, required) — A note about the shift. Visible to providers.
    - `isCallout` (boolean, required) — Whether the shift is marked as a callout. Callout shifts are hidden from reads unless an endpoint explicitly includes them.
    - `workRuleOverride` (uuid | null, required)
  - `punches` (TimecardPunch[], required)
    - `timecardId` (uuid, required)
    - `providerId` (uuid, required)
    - `generated` (boolean, default false)
    - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
    - `updatedAt` (string, required, example "2024-11-20T07:43:34+0000")
    - `action` (string, required)
    - `state` (TimecardPunchState, required, one of `pending`, `approved`, `rejected`)
    - `time` (string, required, example "2024-11-20T07:43:34+0000")
    - `providerNote` (string | null, required, example "Felt sick, had to leave early.")
    - `adminNote` (string | null, required, example "Adjusted to schedule.")
  - `paySegments` (PaySegment[])
    - `type` (PaySegmentType, required, one of `paid`, `unpaid`, `on_call`)
    - `itemId` (string | null)
    - `shiftId` (string | null)
    - `timecardId` (string | null)
    - `startDate` (string, required, example "2024-11-20T07:43:34+0000") — The start date of the pay segment.
    - `endDate` (string, required, example "2024-11-20T07:43:34+0000") — The end date of the pay segment.
    - `payCodes` (string[], required)
    - `overtime` (string[], required)
    - `timeRanges` (string[], required)
    - `workRuleOverride` (string | null)
    - `role` (string | null)
  - `scheduledPaySegments` (PaySegment[])
    - `type` (PaySegmentType, required, one of `paid`, `unpaid`, `on_call`)
    - `itemId` (string | null)
    - `shiftId` (string | null)
    - `timecardId` (string | null)
    - `startDate` (string, required, example "2024-11-20T07:43:34+0000") — The start date of the pay segment.
    - `endDate` (string, required, example "2024-11-20T07:43:34+0000") — The end date of the pay segment.
    - `payCodes` (string[], required)
    - `overtime` (string[], required)
    - `timeRanges` (string[], required)
    - `workRuleOverride` (string | null)
    - `role` (string | null)
  - `warnings` (TimesheetWarning[])
    - `type` (TimesheetWarningType, required, one of `clock_in_early`, `clock_out_early`, `clock_in_late`, `clock_out_late`, `missing_shift`)
    - `punchId` (uuid, required)
  - `errors` (TimesheetError[])
    - `type` (TimesheetErrorType, required, one of `no_clock_out`, `invalid_shift`, `missing_timecard`, `missing_pay_period_template`)
    - `shiftId` (uuid)
    - `timecardId` (uuid)
  - `approval` (TimesheetApproval)
    - `approved` (boolean, required)
    - `ranges` (TimeRange[], required)
      - `startDate` (string, required, example "2024-11-20T07:43:34+0000")
      - `endDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `signOff` (TimesheetSignOff)
    - `signedOff` (boolean, required)
    - `ranges` (TimeRange[], required)
      - `startDate` (string, required, example "2024-11-20T07:43:34+0000")
      - `endDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `historicalCorrections` (HistoricalCorrection[])
    - `status` (HistoricalCorrectionStatus, required, one of `pending`, `completed`)
    - `changes` (HistoricalCorrectionChange[], required)
      - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
      - `actor` (object | null, required) — A null actor indicates a system-generated change
      - `note` (string)
      - `auditLogReference` (uuid | null, required) — A null audit log reference indicates a manually triggered historical correction
      - `auditLogAction` (string | null, required) — The action associated with the audit log reference. Will be null if there is no audit log reference.
    - `payCodeDifference` (HistoricalCorrectionPayCodeDifference[], required)
      - `date` (string, required, example "2024-11-20T07:43:34+0000") — Always represents the start of the day.
      - `payCode` (uuid, required)
      - `role` (string | null, required)
      - `value` (number, required) — The difference in **minutes** (may be negative)
  - `totals` (PayCodeTotal[])
    - `payCodeId` (uuid, required)
    - `roleId` (uuid | null, required) — The role worked during this time, or null for non-working time.
    - `scheduled` (number, required) — The number of minutes scheduled for this pay code and role.
    - `actual` (number, required) — The number of minutes actually worked for this pay code and role.
  - `historicalCorrectionTotals` (PayCodeTotal[])
    - `payCodeId` (uuid, required)
    - `roleId` (uuid | null, required) — The role worked during this time, or null for non-working time.
    - `scheduled` (number, required) — The number of minutes scheduled for this pay code and role.
    - `actual` (number, required) — The number of minutes actually worked for this pay code and role.
- `cursor` (string)

## Errors

- `negative-range` (400) — Time range end date must come after start date.
- `validation` (400) — Input validation failed.