---
title: "Get Workers"
method: GET
path: "/workers/"
tags: ["Workers"]
---

# Get Workers

`GET /workers/`

## Request

- Base URL: `https://v3.api.hypertrack.com`
- URL: `https://v3.api.hypertrack.com/workers/`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/hypertrack/apis/hypertrack-api/docs/workers/get.ts> (a function with typed inputs; its response is checked against the schema)

Fetch workers in a paginated list

## Query parameters

- `from_date` string, nullable
- `to_date` string, nullable
- `limit` integer, nullable
- `include_schedule` boolean
- `include_summary` boolean
- `ops_group_handle` string, nullable
- `profile` string, nullable
- `worker_handle` string, nullable
- `search_term` string, nullable
- `pagination_token` string, nullable
- `device_id` string, uuid, nullable
- `include_deleted` boolean
- `from_time` string, date-time, nullable
- `to_time` string, date-time, nullable
- `filter_outage` string, nullable
- `filter_outage_category` string, nullable
- `filter_geofence_metadata` string, nullable
- `aggregate` boolean
- `work_status` string, nullable
- `filter_status` 'active' | 'inactive' | 'disconnected' | 'null', nullable
- `tracked` boolean, nullable
- `worked` boolean, nullable
- `intended_to_track` boolean, nullable
- `include_lp` boolean, nullable
- `region_filter` string, nullable

## Response `200`

Successful response

- GetWorkersResponse
  - `workers` Worker[], nullable: List of workers
    - `worker_handle` string, required: Unique customer provided identifier for a worker
    - `name` string, nullable: Name of the worker
    - `ops_group_handle` string, required: Unique identifier for an Ops Group to which the worker belongs
    - `product_types` string[], nullable: List of product types used for worker matching during order planning
    - `device_id` string, nullable: Unique ID representing the worker's device
    - `profile` object, nullable: Metadata associated with a worker
    - `work_status` DriverStatus1, required
      - `tracking` boolean, required: Flag indicating whether the worker is currently on work
      - `available` boolean, required: Flag indicating if the worker is available for work
    - `schedule` union[], nullable: List indicating the schedule of a worker for work assignment
      - union
        - DriverDateSchedule
          - `start_time` string, required: Start time represented by HH:mm of the worker's day schedule
          - `end_time` string, required: End time represented by HH:mm of the worker's day schedule
          - `date` string, required: Date on which the worker is available for work
          - `ops_group_handle` string, nullable: Unique identifier for an Ops Group
          - `priority` integer, nullable: Priority of schedule of a worker
        - DriverRecurringSchedule
          - `start_time` string, required: Start time represented by HH:mm of the worker's day schedule
          - `end_time` string, required: End time represented by HH:mm of the worker's day schedule
          - `day_of_week` 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY', required: Day of the week when the worker is available for work
          - `ops_group_handle` string, nullable: Unique identifier for an Ops Group
          - `priority` integer, nullable: Priority of schedule of a worker
    - `deleted` boolean, nullable: Flag indicating whether the worker was deleted
    - `created_at` string, required: Timestamp at which the worker was created
    - `home` union: Worker home
      - LocationWithoutRadiusResponse
        - `address` string, nullable: Address for the location
        - `geometry` LocationGeometryResponse, required
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
      - unknown
    - `deleted_at` string, nullable: Timestamp at which the worker was deleted
    - `location` union: Last known location of the worker.
      - MovementLocationResponse
        - `geometry` LocationGeometryResponse, required
          - `type` string, required: Geometry type
          - `coordinates` unknown[], required: Location coordinates represented as list of [longitude, latitude].
            - unknown
        - `accuracy` number, nullable: Accuracy in meters for the location
        - `bearing` number, nullable: Directional position in degrees for the location
        - `speed` number, nullable: Speed in meters per second at this location
        - `recorded_at` string, nullable: Timestamp associated with the last known location of the worker.
      - unknown
    - `device_status` union: Current status of the device used by the worker
      - DeviceStatus1
        - `value` string, required: Status of the worker's device - `active` `disconnected` `inactive`
        - `data` object, required: Data associated with the worker's device status - `reason`, `activity`
      - unknown
    - `unavailable_on` string[], nullable: List of dates (YYYY-MM-DD) on which the worker is not available
    - `summary` union: Summary of work done by the worker during the specified time range. Default last 24 hours.
      - DriverSummary1
        - `orders` OrderSummary1, required
          - `total` integer, required: Total orders
          - `completed` integer, required: Orders completed
          - `cancelled` integer, required: Orders cancelled
          - `tracked` integer, required: Orders currently being tracked
          - `assigned` integer, required: Orders assigned
          - `completed_tasks` integer, required: Order tasks completed
        - `geotags` integer, nullable: Number of Geotags created by the worker in the specified time range.
        - `visits` integer, nullable: Number of Visits made by the worker during the specified time range.
        - `intended_track_duration` integer, required: Total duration (in seconds) for which the worker was supposed to be tracked during the specified time range.
        - `outage_duration` integer, required: Total duration (in seconds) for which the worker could not be tracked (in outage) during the specified time range.
        - `outage_distance` integer, required: Total estimated distance (in meters) covered by the worker while he/she could not be tracked during the specified time range.
        - `outage_summary` DriverOutageSummary1[], required: List of outages experienced by the worker during the specified time range.
          - `code` string, required: Code indicating the type of outage
          - `label` string, required: Text indicating the type of outage
          - `description` string, required: Text describing the outage.
          - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic', required: String indicating the category of outage
          - `duration` integer, required: Sum total duration of all outages experienced with this `code` in the specified time range.
          - `distance` integer, required: Sum total (estimated) distance covered during all outages experienced with this `code` in the specified time range.
        - `tracked_duration` integer, required: Total duration (in seconds) for which the worker was actually tracked during the specified time range.
        - `tracked_distance` integer, required: Total distance (in meters) driven by the worker while the worker was actually tracked during the specified time range.
        - `avg_distance_per_visit` number, required: Average distance (in meters) driven by the worker per visit while the worker was actually tracked during the specified time range.
        - `drive_duration` integer, required: Total duration (seconds) for which the worker was driving during the specified time range.
        - `walk_duration` integer, required: Total duration (seconds) for which the worker was walking during the specified time range.
        - `stop_duration` integer, required: Total duration (seconds) for which the worker had stopped during the specified time range.
        - `order_duration` integer, required: Total duration (seconds) which the worker had spent delivering orders.
        - `visit_duration` integer, required: Total duration (seconds) which the worker had spent doing visits.
        - `geotag_duration` integer, required: Total duration (seconds) which the worker had spent creating geotags.
        - `tracking_rate` number, nullable: Average tracking rate of the worker during the specified time range.
        - `stop_count` integer, nullable: Number of stops.
        - `walk_count` integer, nullable: Number of walks.
        - `drive_count` integer, nullable: Number of drives.
        - `distance` integer, nullable: Total distance (tracked + outage) in meters covered by the worker during the specified time range.
        - `available_duration` integer, nullable: Total duration (in seconds) for which the worker was actually tracked during the specified time range.<br />__Please use the field `tracked_duration` instead.__
        - `work_duration` integer, nullable: Total duration (seconds) spent on work by the worker in the specified time range.
        - `disconnected_duration` integer, nullable: Total duration (in seconds) for which the worker was supposed to be tracked, but actually in a disconnected state.
        - `status` DriverSummaryStatus1, required
          - `intended_to_track` boolean, required: Boolean flag indicating whether worker was supposed to be tracked during the specified period.
          - `tracked` boolean, required: Boolean flag indicating whether worker was actually tracked during the specified period.
          - `worked` boolean, required: Boolean flag indicating whether worker had worked during the specified period.
          - `available` boolean, required: Boolean flag indicating whether worker was marked available during the specified period.
      - unknown
    - `location_permission` union: Last known location permission on the worker's device
      - LocationPermission1
        - `state` 'always' | 'foreground_only' | 'never' | 'location_imprecise' | 'unknown', required: State of location permission
        - `recorded_at` string, nullable: Time stamp of the last known location permission
      - unknown
    - `device_info` union: Information of the Device associated with Worker
      - DeviceInfo
        - `timezone` string, required: Timezone of the device
        - `os_name` string, required: Operating system running on the device
        - `device_brand` string, required: Brand of the device
        - `sdk_version` string, required: HyperTrack SDK version used on the device
        - `device_model` string, required: Model of the device
        - `network_operator` string, nullable: Network operator used by the device
        - `os_version` string, required: Operating system version on the device
        - `os_hardware_identifier` string, required: Hardware identification number for the device
        - `app_name` string, required: App name on the device
        - `app_version_string` string, nullable: App version used on the device
        - `app_version_number` string, nullable: App version number used on the device
      - unknown
    - `battery` union: Information of the battery status.
      - BatteryStatus1
        - `battery_percent` integer, required: Integer indicating the percent of charge on the battery.
        - `recorded_at` string, required: Timestamp of the reading
      - unknown
    - `timezone` string, nullable: Timezone of the worker
  - `pagination_token` string, nullable: Identifier used to fetch the next page of data
  - `aggregate` union: Combined aggregate work metrics for workers in the given time range. Default last 24 hours.
    - WorkerAggregate
      - `geotags` GeotagsAggregate
        - `count` integer, required: Number of geotags generated in the given time range
        - `distance` union: Stats related to workers' distance
          - GeotagStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
        - `duration` union: Stats related to workers' duration
          - GeotagStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
        - `deviation` union: Stats related to the geotag deviation
          - GeotagStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
      - `orders` OrdersAggregate
        - `count` CountGroup, required
          - `total` integer, required: Total number of orders
          - `completed` integer, nullable: Total number of completed orders
          - `cancelled` integer, nullable: Total number of cancelled orders
          - `assigned` integer, nullable: Total number of assigned orders
          - `tracked` integer, nullable: Total number of tracked orders
        - `distance` union: Stats related to workers' distance
          - OrderStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
        - `duration` union: Stats related to workers' duration
          - OrderStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
        - `deviation` union: Stats related to the geotag deviation
          - OrderStats
            - `mean` number, nullable: Average value for the metric
            - `min` number, nullable: Minimum value for the metric
            - `max` number, nullable: Maximum value for the metric
            - `stdev` number, nullable: Standard deviation for the metric
            - `mean_by_driver` number, nullable: Average value per worker for the metric
            - `sum` number, required: Total value of the metric
          - unknown
      - `workers` DriversAggregate1
        - `total` integer, nullable: Total number of workers matching applied filters
        - `total_intended_to_track` integer, nullable: Workers expected to be tracked during the period
        - `worked` integer, nullable: Workers who performed work (orders, geotags, or visits)
        - `tracked` integer, nullable: Workers successfully tracked during the period
        - `untracked` integer, nullable: Workers with tracking intent but failed due to actionable outage
        - `disconnected` integer, nullable: Workers with tracking intent but failed without actionable outage
        - `tracked_not_worked` integer, nullable: Workers tracked but with no work activity
      - `summary` SummaryAggregate
        - `tracked_duration` integer, nullable: Total tracked duration of all workers.
        - `tracked_distance` integer, nullable: Total tracked distance of all workers.
        - `outage_duration` integer, nullable: Total outage duration of all workers.
        - `outage_distance` integer, nullable: Total outage distance of all workers.
        - `drive_duration` integer, nullable: Total drive duration of all workers.
        - `stop_duration` integer, nullable: Total stop duration of all workers.
        - `walk_duration` integer, nullable: Total walk duration of all workers.
      - `tracking_rate` number, nullable: Tracking Rate
      - `outage_summary` DriverOutageSummaryAggregate[], nullable: Aggregate information of worker outage summaries in the specified time range
        - `code` string, required: Code indicating the type of outage
        - `label` string, required: Text indicating the type of outage
        - `description` string, required: Text describing the outage.
        - `category` 'behavioural' | 'adversarial' | 'reachability' | 'os' | 'sporadic', required: String indicating the category of outage
        - `duration` integer, required: Total duration of all instances of concerned outage.
        - `duration_untracked` integer, required: Total duration of all instances of concerned outage observed for untracked workers.
        - `duration_tracked` integer, required: Total duration of all instances of concerned outage observed for tracked workers.
        - `distance` integer, required: Estimated distance covered during all instances of concerned outage.
      - `location_permission_state_counts` LocationPermissionStateCounts
        - `always` integer, required
        - `foreground_only` integer, required
        - `never` integer, required
        - `unknown` integer, required
      - `visits` VisitAggregateModel
        - `count` integer, required: Number of visits in the given time range
    - unknown

## Other responses

- `400`: Validation error
- `401`: Authentication error

---

[API](https://skmtc.dev/hypertrack/apis/hypertrack-api.md) - [All operations](https://skmtc.dev/hypertrack/apis/hypertrack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hypertrack/apis/hypertrack-api/revisions/389326c4c9c8?raw)