---
title: "Locate a worker"
method: POST
path: "/workers/{worker_handle}/locate"
tags: ["Workers"]
---

# Locate a worker

`POST /workers/{worker_handle}/locate`

## Request

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

Initiates an async worker locate. The implementation sets the worker's availability=true (waking the SDK), pulls a fresh location from each currently-linked device, then sets availability back to false. Returns immediately with a request_id; poll the GET endpoint or listen for the `locate` webhook for the final result.

## Path parameters

- `worker_handle` string, required

## Request body

- CreateLocateRequest

## Response `201`

Successful response

- LocateResponse
  - `request_id` string, required: Unique identifier for the locate request.
  - `worker_handle` string, required: Unique customer provided identifier for a worker.
  - `status` 'pending' | 'completed' | 'error', required: Worker-level rollup: `pending` while async work is in flight, `completed` once the async work is done (introspect `devices[]` for per-device outcomes — connection state lives on `device_status`, outage detail on `outage_reasons`), `error` on unexpected internal failure.
  - `devices` LocateDeviceResultResponse[], nullable: Per-device locate results, newest session first. Empty array when the worker has no active device sessions; see each entry's `outage_reasons` for per-device outages.
    - `device_id` string, required: Unique ID representing the device that was located.
    - `status` 'pending' | 'completed' | 'error', required: Per-device locate status: `pending` while async work is in flight, `completed` once the async work for this device is done (inspect `location` / `outage_reasons` / `device_status` for the outcome), `error` on unexpected processing failure.
    - `location` union: Location pulled from this device, if any.
      - 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
    - `location_permission` union: Last known location permission for this 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_status` union: Connection-level outcome for this locate attempt. Populated when the SDK didn't come back online within the wake-and-wait budget (`value` = `disconnected`). Same shape as `worker.device_status`.
      - DeviceStatus
        - `value` string, required: Status of the driver's device - `active` `disconnected` `inactive` `available` `unavailable`
        - `data` object, required: Data associated with the driver's device status - `reason`, `activity`
      - unknown
    - `outage_reasons` DriverOutageSummary[], nullable: Outage details reported by the SDK; same shape as `worker.summary.outages`.
      - `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.
    - `completed_at` string, nullable: Timestamp at which this device's locate reached terminal state.
  - `created_at` string, nullable: Timestamp at which the locate request was created.
  - `updated_at` string, nullable: Timestamp of last update to the locate request.
  - `completed_at` string, nullable: Timestamp at which the locate request reached a terminal state.

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `404`: Not found

---

[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)