> 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-api/user-api/resources/tracking/status/tracker.md).

# Tracker's working status

Read and set the working status a particular tracker is currently in.

These operations work on the current status of a tracker, rather than on the [statuses](/docs/navixy-api/user-api/resources/tracking/status.md) and [lists](/docs/navixy-api/user-api/resources/tracking/status/listing.md) that define what it can be set to.

A tracker can only be set to a status from the list assigned to it, and only when that list is supervisor-controlled. A list that only its own employee may change returns error 13 to a supervisor attempting the change.

Setting a tracker to the status it already holds returns error 263 rather than succeeding silently.

## API actions

API base path: `/status/tracker`.

***

## Assign working status to tracker

> Set a tracker's current working status, and return the change that resulted.\
> \
> The status must belong to the list assigned to that tracker, and \*\*the list must be supervisor-controlled\*\*: a list only its employee may change returns error 13.\
> \
> The change is recorded with origin \`supervisor\` and the tracker's last known location. Assigning the status the tracker already holds returns error 263.\
> \
> Not allowed for clones. Requires the \`statuses\` tariff feature on at least one tracker. Without it the call returns error 236.\
> \
> Also accepts GET with the same parameters as query-string values.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Working statuses","description":"Working statuses, the activity a tracker is marked as being in, the lists they are grouped into, and the assignment of a status to a tracker. All resources under the /status/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"StatusChange":{"type":"object","description":"One change of a tracker's working status, recording what it changed from and to, where, and who changed it. May be `null` where a tracker's status has never changed.","properties":{"id":{"type":"integer","description":"ID of the change record."},"old_status_id":{"type":["integer","null"],"description":"The status held before the change, or `null` when none was set."},"new_status_id":{"type":["integer","null"],"description":"The status held after the change, or `null` when the status was removed, which happens when the tracker is moved to a different status list."},"location":{"type":["object","null"],"description":"Where the tracker was when the status changed, or `null` when the location was unknown.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point, or an empty string when none was resolved."}}},"changed":{"type":"string","description":"When the change was recorded, in `YYYY-MM-DD HH:MM:SS` format."},"origin":{"type":"string","description":"Who made the change: `supervisor` from the monitoring interface, `employee` from the Mobile Tracker App.","enum":["supervisor","employee"]}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/status/tracker/assign":{"post":{"tags":["Working statuses"],"summary":"Assign working status to tracker","description":"Set a tracker's current working status, and return the change that resulted.\n\nThe status must belong to the list assigned to that tracker, and **the list must be supervisor-controlled**: a list only its employee may change returns error 13.\n\nThe change is recorded with origin `supervisor` and the tracker's last known location. Assigning the status the tracker already holds returns error 263.\n\nNot allowed for clones. Requires the `statuses` tariff feature on at least one tracker. Without it the call returns error 236.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"statusTrackerAssign","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1},"new_status_id":{"type":"integer","description":"ID of the working status to assign. Must belong to the status list assigned to this tracker.","minimum":1}},"required":["tracker_id","new_status_id"]}}}},"responses":{"200":{"description":"The resulting change","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"last_change":{"$ref":"#/components/schemas/StatusChange"}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 236: no tracker on the account has the `statuses` feature.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 13: the status list does not allow a supervisor to change the status. Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 219: the tracker is a clone.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 204: the status list assigned to this tracker has no status with this ID.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 13 - Operation not permitted, when the status list does not allow a supervisor to change the status.
* 201 - Not found in the database, when the authorized user has no tracker with the given ID.
* 204 - Entity not found, when the list assigned to the tracker holds no status with the given ID.
* 208 - Device blocked, when the tracker exists but is blocked, whether by tariff restrictions or for another reason.
* 219 - Not allowed for clones of the device, when the given tracker is a clone.
* 236 - Feature unavailable due to tariff restrictions, when no tracker on the account has the `statuses` tariff feature.
* 263 - No change needed, old and new values are the same, when the new status matches the tracker's current one.

***

## List trackers' working statuses

> Return the current working status and last change for each of the given trackers.\
> \
> The result is keyed by tracker ID. \`trackers\` is required here, unlike the beacon calls: an empty body is rejected.\
> \
> Requires the \`statuses\` tariff feature on at least one tracker. Without it the call returns error 236.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Working statuses","description":"Working statuses, the activity a tracker is marked as being in, the lists they are grouped into, and the assignment of a status to a tracker. All resources under the /status/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"TrackerCurrentStatus":{"type":"object","description":"A tracker's working status as it stands now, with the change that produced it.","properties":{"current_status":{"oneOf":[{"$ref":"#/components/schemas/WorkingStatus"},{"type":"null"}],"description":"The status the tracker holds now, or `null` when none is set."},"last_change":{"$ref":"#/components/schemas/StatusChange"}}},"WorkingStatus":{"type":"object","description":"One entry in a status list: an activity a tracker can be marked as being in, such as busy or on a break.","properties":{"id":{"type":"integer","description":"Working status ID. Read-only, assigned on creation, and required when updating.","minimum":1},"label":{"type":"string","description":"Human-readable label. 1 to 200 printable characters, trimmed, and cannot be blank.","minLength":1,"maxLength":200},"color":{"type":"string","description":"Display colour as six hexadecimal digits, **without a leading `#`**, for example `E57373`.","pattern":"^[0-9a-fA-F]{6}$"}}},"StatusChange":{"type":"object","description":"One change of a tracker's working status, recording what it changed from and to, where, and who changed it. May be `null` where a tracker's status has never changed.","properties":{"id":{"type":"integer","description":"ID of the change record."},"old_status_id":{"type":["integer","null"],"description":"The status held before the change, or `null` when none was set."},"new_status_id":{"type":["integer","null"],"description":"The status held after the change, or `null` when the status was removed, which happens when the tracker is moved to a different status list."},"location":{"type":["object","null"],"description":"Where the tracker was when the status changed, or `null` when the location was unknown.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point, or an empty string when none was resolved."}}},"changed":{"type":"string","description":"When the change was recorded, in `YYYY-MM-DD HH:MM:SS` format."},"origin":{"type":"string","description":"Who made the change: `supervisor` from the monitoring interface, `employee` from the Mobile Tracker App.","enum":["supervisor","employee"]}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/status/tracker/list":{"post":{"tags":["Working statuses"],"summary":"List trackers' working statuses","description":"Return the current working status and last change for each of the given trackers.\n\nThe result is keyed by tracker ID. `trackers` is required here, unlike the beacon calls: an empty body is rejected.\n\nRequires the `statuses` tariff feature on at least one tracker. Without it the call returns error 236.","operationId":"statusTrackerList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trackers":{"type":"array","description":"Tracker IDs belonging to the current account. Cannot be an empty array.","items":{"type":"integer"}}},"required":["trackers"]}}}},"responses":{"200":{"description":"Current statuses by tracker","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"type":"object","description":"Map of tracker ID to that tracker's current status. Keys are tracker IDs as strings.","additionalProperties":{"$ref":"#/components/schemas/TrackerCurrentStatus"}}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 236: no tracker on the account has the `statuses` feature.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 217: one or more of the tracker IDs does not exist or belongs to another user. Error 221: the device limit set for the account's dealer has been exceeded.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 217 - List contains nonexistent entities, when one of the given tracker IDs belongs to no tracker, or to a tracker owned by another user.
* 221 - Device limit exceeded, when the device limit set for the user's dealer has been exceeded.
* 236 - Feature unavailable due to tariff restrictions, when no tracker on the account has the `statuses` tariff feature.

***

## Read tracker's working status

> Return one tracker's current working status and the last change to it.\
> \
> Both may be \`null\`: \`current\_status\` is null when no status is set now, and \`last\_change\` is null when the status has never changed.\
> \
> Requires the \`statuses\` tariff feature on at least one tracker. Without it the call returns error 236.\
> \
> Also accepts GET with the same parameters as query-string values.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Working statuses","description":"Working statuses, the activity a tracker is marked as being in, the lists they are grouped into, and the assignment of a status to a tracker. All resources under the /status/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"WorkingStatus":{"type":"object","description":"One entry in a status list: an activity a tracker can be marked as being in, such as busy or on a break.","properties":{"id":{"type":"integer","description":"Working status ID. Read-only, assigned on creation, and required when updating.","minimum":1},"label":{"type":"string","description":"Human-readable label. 1 to 200 printable characters, trimmed, and cannot be blank.","minLength":1,"maxLength":200},"color":{"type":"string","description":"Display colour as six hexadecimal digits, **without a leading `#`**, for example `E57373`.","pattern":"^[0-9a-fA-F]{6}$"}}},"StatusChange":{"type":"object","description":"One change of a tracker's working status, recording what it changed from and to, where, and who changed it. May be `null` where a tracker's status has never changed.","properties":{"id":{"type":"integer","description":"ID of the change record."},"old_status_id":{"type":["integer","null"],"description":"The status held before the change, or `null` when none was set."},"new_status_id":{"type":["integer","null"],"description":"The status held after the change, or `null` when the status was removed, which happens when the tracker is moved to a different status list."},"location":{"type":["object","null"],"description":"Where the tracker was when the status changed, or `null` when the location was unknown.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"address":{"type":"string","description":"Address at that point, or an empty string when none was resolved."}}},"changed":{"type":"string","description":"When the change was recorded, in `YYYY-MM-DD HH:MM:SS` format."},"origin":{"type":"string","description":"Who made the change: `supervisor` from the monitoring interface, `employee` from the Mobile Tracker App.","enum":["supervisor","employee"]}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/status/tracker/read":{"post":{"tags":["Working statuses"],"summary":"Read tracker's working status","description":"Return one tracker's current working status and the last change to it.\n\nBoth may be `null`: `current_status` is null when no status is set now, and `last_change` is null when the status has never changed.\n\nRequires the `statuses` tariff feature on at least one tracker. Without it the call returns error 236.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"statusTrackerRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1}},"required":["tracker_id"]}}}},"responses":{"200":{"description":"The tracker's working status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"current_status":{"oneOf":[{"$ref":"#/components/schemas/WorkingStatus"},{"type":"null"}],"description":"The status the tracker holds now, or `null` when none is set."},"last_change":{"$ref":"#/components/schemas/StatusChange"}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"402":{"description":"Error 236: no tracker on the account has the `statuses` feature.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 201 - Not found in the database, when the authorized user has no tracker with the given ID.
* 208 - Device blocked, when the tracker exists but is blocked, whether by tariff restrictions or for another reason.
* 236 - Feature unavailable due to tariff restrictions, when no tracker on the account has the `statuses` tariff feature.


---

# 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-api/user-api/resources/tracking/status/tracker.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.