> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/tracking/overview.md).

# Tracking overview

Tracking provides the live state of assets and their devices, the streams that follow that state, and the trips and stops calculated from device messages.

{% hint style="warning" %}
**Navixy GraphQL API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}

**Tracking** is the product that answers where your assets are and what their devices report. It is one of the products served by [Navixy GraphQL API](/docs/navixy-graphql-api/readme.md). [Business Data Repository](/docs/navixy-graphql-api/business-data-repository/overview.md) stores the records of an asset and of the devices linked to it. Tracking returns what those devices report: position, connectivity, motion, and sensor readings, plus the trips and stops calculated from them.

All Tracking queries are nested under the `tracking` field of the `Query` type. The two state streams are fields of the `Subscription` type. The shared pages of this space cover the request format, [authentication](/docs/navixy-graphql-api/authentication.md), [pagination](/docs/navixy-graphql-api/pagination.md), and [error handling](/docs/navixy-graphql-api/error-handling.md). For the endpoint and the headers of a request, see [Getting started](/docs/navixy-graphql-api/getting-started.md).

## Purpose and capabilities

Tracking enables you to:

* Read the current state of one asset, of every asset in a workspace, or of a single device
* Follow that state as it changes, without polling for it
* Read the trips and stops of an asset or a device over a period of time
* Read the dictionary that gives every device reading a title, a unit, and a kind

## Key concepts

<table><thead><tr><th width="147.48895263671875">Term</th><th>Definition</th></tr></thead><tbody><tr><td><strong>Device state</strong></td><td>The last known values for one device: where it is, whether it is reporting, whether it is moving, and what its sensors last sent.</td></tr><tr><td><strong>Asset state</strong></td><td>The states of the devices linked to one asset, as separate entries. Tracking doesn't merge them, because two devices on one asset can report the same value differently.</td></tr><tr><td><strong>Reading</strong></td><td>A named value that a device sent, such as an ignition state or a fuel level. Every reading includes the moment it arrived, so the readings of one state can differ in age.</td></tr><tr><td><strong>Field dictionary</strong></td><td>The catalog of reading names. It gives a name a title, a unit, and a kind, so a client can render a reading it has never seen.</td></tr><tr><td><strong>Stream</strong></td><td>A subscription that pushes the whole state of a followed asset or device every time it reports. A client replaces its copy of the state and keeps no update logic of its own.</td></tr><tr><td><strong>Trip</strong></td><td>A segment of movement between two stops. Trips aren't stored: Tracking calculates them from the messages of a device when you ask for them.</td></tr><tr><td><strong>Stop</strong></td><td>A period during which a device stayed in one place. Calculated on request, in the same way as a trip.</td></tr></tbody></table>

## Device states

A device has three states, and each one changes on its own:

* The **lifecycle** state records whether a device is registered and active. It belongs to the device record, so you read it from [Business Data Repository](/docs/navixy-graphql-api/business-data-repository/overview.md).
* The **connectivity** state records whether a device is reporting. Tracking calculates it from the time of the last message and doesn't store it.
* The **motion** state records whether a device is moving or stopped.

One value can't express all three. A device can be active and silent, and it can be reporting while inactive.

## Navigation

The Tracking documentation has two guides and an API reference with one page per concept.

The guides cover the two views that a fleet application builds from Tracking:

* [Building a live fleet map](/docs/navixy-graphql-api/tracking/guides/building-a-live-fleet-map.md) reads the state of every asset in a workspace, places each asset on the map, renders its readings with the field dictionary, and keeps the map current with a state stream.
* [Reading a vehicle trip history](/docs/navixy-graphql-api/tracking/guides/reading-a-vehicle-trip-history.md) requests the trips and stops of one device for a period, with totals, the route of each trip, and the continuation of a partial result.

The [Tracking API reference](/docs/navixy-graphql-api/tracking/api-reference.md) documents the operations and types, one page per concept:

* [Live state](/docs/navixy-graphql-api/tracking/api-reference/state.md) documents the state of a device and the state of an asset, with the queries that read them.
* [State streams](/docs/navixy-graphql-api/tracking/api-reference/state/streams.md) documents the subscriptions that push state as it changes, and what each message contains.
* [Readings and the field dictionary](/docs/navixy-graphql-api/tracking/api-reference/readings.md) documents how a reading is built and what the dictionary says about it.
* [Trips and stops](/docs/navixy-graphql-api/tracking/api-reference/trips.md) documents the trips and stops of a device, and the settings that control them.

For the types that Tracking shares with the other products, and for an index of the whole API, see the [Core API reference](/docs/navixy-graphql-api/core-api-reference.md).

{% hint style="warning" %}
The API supports [GraphQL introspection](/docs/navixy-graphql-api/graphql-basics.md#introspection) for authenticated users. You can also check the public [GraphQL schema](/docs/navixy-graphql-api/developer-resources/public-graphql-schema.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-graphql-api/tracking/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.