---
title: "Retrieving a Tracked Subject"
method: GET
path: "/geo/subjects/{externalSubjectId}"
tags: ["Tracked Subjects"]
---

# Retrieving a Tracked Subject

`GET /geo/subjects/{externalSubjectId}`

## Request

- Base URL: `https://api.flocksafety.com/api/v3`
- URL: `https://api.flocksafety.com/api/v3/geo/subjects/{externalSubjectId}`
- Auth: HTTP bearer

Get a single subject's current location.

## Path parameters

- `externalSubjectId` string, required

## Response `200`

Get a single subject's current location

- Heartbeat
  - `subjectId` string: ID of the subject in flocks system
  - `subjectType` 'vehicle' | 'person' | 'drone' | 'other', required: base type of the subject. This is used to filter subjects on the map
  - `subjectSubtype` string, required: subtype of the subject. This is used to filter subjects on the map
  - `externalId` string, required: ID of the subject in your system. Must be unique per organization.
  - `createdAt` string, date-time: RFC3339 UTC datetime string of when subject was created
  - `updatedAt` string, date-time: RFC3339 UTC datetime string of when subject was last updated. Use this if different time than createdAt or the current time.
  - `disableAt` string, date-time: RFC3339 UTC datetime string of when subject should be inactive
  - `latitude` number, required
  - `longitude` number, required
  - `altitude` number: altitude in meters, defaults to 0.0 and returned as 0.0 if not provided
  - `additionalMetadata` object: flat json object, defaults to {} and returned as {} if not provided
    - `type` 'string' | 'number' | 'boolean': What type the value of the metadata value is
    - `value` object: value of the metadata. Must be a string, number, or boolean
  - `deviceLink` string: URL to the device, defaults to "" and returned as "" if not provided
  - `deviceStatus` string: status of the device such as buffering, recording, etc
  - `isRecording` boolean: if the subject is recording or not
  - `nickname` string: nickname of the subject
  - `isLawEnforcement` boolean: if the subject is a law enforcement subject or not

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found (provided id doesn't match any existing)

---

[API](https://skmtc.dev/flocksafety/apis/inbound-geo-api.md) - [All operations](https://skmtc.dev/flocksafety/apis/inbound-geo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/flocksafety/apis/inbound-geo-api/revisions/c5cb1df0d44d?raw)