> 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/commons/history.md).

# History

The record of what trackers, assets, and users did, and the operations that read and mark it.

The event history is the Navixy platform's record of what happened: a rule that fired, a device that went offline, a user who changed something. It is what a notification feed is built from, and what a reader consults after the fact.

History is read through several lists, split by what the events are about: [trackers](/docs/navixy-api/user-api/resources/commons/history/history_tracker.md), [assets](/docs/navixy-api/user-api/resources/commons/history/asset-events.md), and [the account's own users](/docs/navixy-api/user-api/resources/commons/history/history-user.md). The operations here work on individual entries, reading one and marking entries as read. [Unread events](/docs/navixy-api/user-api/resources/commons/history/history_unread.md) covers the unread subset, and [event types](/docs/navixy-api/user-api/resources/commons/history/history_type.md) lists what an event can be.

## Tracker history entry

## The HistoryEntry object

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"HistoryEntry":{"type":"object","description":"One recorded event: a rule firing, a device going offline, a task changing state, and so on.","properties":{"id":{"type":"integer","description":"ID of the event.","format":"int64"},"type":{"type":"string","description":"Kind of device the event came from.","enum":["socket","tracker","camera"]},"is_read":{"type":"boolean","description":"`true` when the user has seen the notification and it has been marked read."},"message":{"type":"string","description":"Notification message, **shortened to 256 characters**. The untruncated text is in `extra.full_message` when it was shortened."},"time":{"type":"string","description":"When the notification was received."},"event":{"type":"string","description":"Event type. The available values come from `history/type/list`."},"tracker_id":{"type":"integer","description":"ID of the tracker, also known as `object_id`."},"rule_id":{"type":["integer","null"],"description":"ID of the rule that produced the event, when there was one."},"track_id":{"type":"integer","description":"ID of the track the event happened on, or 0 when no track is associated."},"address":{"type":["string","null"],"description":"Street address of `location`, repeated here for convenience. Null when the event carries no location."},"location":{"type":"object","description":"Where the event happened.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"precision":{"type":"integer","description":"Accuracy of the fix in metres."},"address":{"type":"string","description":"Human-readable address of the point, or an empty string when none was resolved. **Nested here, not at the top level of the entry.**"}}},"assets":{"type":"array","description":"Assets linked to the event, each naming an identifier and a type. Present on entries the platform could associate with a vehicle or an employee.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the asset."},"type":{"type":"string","description":"What kind of asset it is.","enum":["vehicle","employee"]}}}},"extra":{"type":"object","description":"Event-specific extras. Which of these appear depends on the event type.","properties":{"employee_full_name":{"type":"string","description":"Full name of the employee the event relates to. Added by the history service when it can resolve one."},"vehicle_label":{"type":"string","description":"Label of the vehicle the event relates to. Added by the history service when it can resolve one."},"task_id":{"type":["integer","null"],"description":"Related task ID."},"parent_task_id":{"type":["integer","null"],"description":"Related parent task ID, for a task checkpoint event."},"counter_id":{"type":["integer","null"],"description":"Related counter ID."},"service_task_id":{"type":["integer","null"],"description":"Related service work ID."},"checkin_id":{"type":["integer","null"],"description":"Related check-in ID."},"place_ids":{"type":"array","description":"Related place IDs.","items":{"type":"integer"}},"places_total_count":{"type":"integer","description":"Total number of related places."},"last_known_location":{"type":"boolean","description":"`true` when the location may be out of date."},"tracker_label":{"type":"string","description":"Label of the related tracker."},"emergency":{"type":"boolean","description":"`true` for an emergency event, matching the same flag on the rule."},"zone_ids":{"type":"array","description":"Related geofence IDs.","items":{"type":"integer"}},"zone_labels":{"type":"array","description":"Related geofence labels.","items":{"type":"string"}},"proximity_object_id":{"type":"integer","description":"ID of the tracker involved in a proximity event."},"employee_id":{"type":"integer","description":"ID of the driver at the time of the event."},"sensor_id":{"type":"integer","description":"Related sensor ID."},"sensor_name":{"type":"string","description":"Related sensor name."},"sensor_calculated_value":{"type":"string","description":"Related sensor value."},"full_message":{"type":"string","description":"The full event message, present when `message` was shortened."},"precision":{"type":"integer","description":"Precision of the location in metres."},"command":{"type":"object","description":"Present on a `command_sent` event: a command dispatched from a tracker's Commands block.","properties":{"name":{"type":"string","description":"Name of the command that was sent."},"param":{"type":["string","null"],"description":"Value substituted for the command's `<>` placeholder, when it has one."},"response":{"type":"object","description":"Delivery result. A `hardware` command populates only `success`; an `http` command populates `status` and `body` (and `error` in place of them when the request itself failed) instead, leaving `success` absent.","properties":{"status":{"type":["integer","null"],"description":"HTTP status code returned by the destination endpoint. Present only for an `http` command."},"body":{"type":["string","null"],"description":"Raw response body from the destination endpoint, truncated to fit the event's storage limit. Present only for an `http` command."},"error":{"type":["string","null"],"description":"Error message, up to 256 characters, when the request to the destination endpoint could not be completed. Present only for an `http` command, and only when the request failed."},"success":{"type":["boolean","null"],"description":"Whether the command was sent to the device. Present only for a `hardware` command."}}}}}},"additionalProperties":true}}}}}}
```

The event types an entry's `event` field can carry come from [`history/type/list`](/docs/navixy-api/user-api/resources/commons/history/history_type.md#post-history-type-list). Date and time values follow the [platform formats](/docs/navixy-api/general/api-conventions.md#data-types).

For a walkthrough, see [how to work with notifications](/docs/navixy-api/user-api/guides/rules-notifications/work-with-notifications.md).

## API actions

API base path: `/history`.

Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes).

***

## Read history entry

> Return one history entry by ID.\
> \
> 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":"History","description":"The events history: what happened on trackers and assets, what the account itself did, and which entries the user has read. All resources under the /history/ 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":{"HistoryEntry":{"type":"object","description":"One recorded event: a rule firing, a device going offline, a task changing state, and so on.","properties":{"id":{"type":"integer","description":"ID of the event.","format":"int64"},"type":{"type":"string","description":"Kind of device the event came from.","enum":["socket","tracker","camera"]},"is_read":{"type":"boolean","description":"`true` when the user has seen the notification and it has been marked read."},"message":{"type":"string","description":"Notification message, **shortened to 256 characters**. The untruncated text is in `extra.full_message` when it was shortened."},"time":{"type":"string","description":"When the notification was received."},"event":{"type":"string","description":"Event type. The available values come from `history/type/list`."},"tracker_id":{"type":"integer","description":"ID of the tracker, also known as `object_id`."},"rule_id":{"type":["integer","null"],"description":"ID of the rule that produced the event, when there was one."},"track_id":{"type":"integer","description":"ID of the track the event happened on, or 0 when no track is associated."},"address":{"type":["string","null"],"description":"Street address of `location`, repeated here for convenience. Null when the event carries no location."},"location":{"type":"object","description":"Where the event happened.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"precision":{"type":"integer","description":"Accuracy of the fix in metres."},"address":{"type":"string","description":"Human-readable address of the point, or an empty string when none was resolved. **Nested here, not at the top level of the entry.**"}}},"assets":{"type":"array","description":"Assets linked to the event, each naming an identifier and a type. Present on entries the platform could associate with a vehicle or an employee.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the asset."},"type":{"type":"string","description":"What kind of asset it is.","enum":["vehicle","employee"]}}}},"extra":{"type":"object","description":"Event-specific extras. Which of these appear depends on the event type.","properties":{"employee_full_name":{"type":"string","description":"Full name of the employee the event relates to. Added by the history service when it can resolve one."},"vehicle_label":{"type":"string","description":"Label of the vehicle the event relates to. Added by the history service when it can resolve one."},"task_id":{"type":["integer","null"],"description":"Related task ID."},"parent_task_id":{"type":["integer","null"],"description":"Related parent task ID, for a task checkpoint event."},"counter_id":{"type":["integer","null"],"description":"Related counter ID."},"service_task_id":{"type":["integer","null"],"description":"Related service work ID."},"checkin_id":{"type":["integer","null"],"description":"Related check-in ID."},"place_ids":{"type":"array","description":"Related place IDs.","items":{"type":"integer"}},"places_total_count":{"type":"integer","description":"Total number of related places."},"last_known_location":{"type":"boolean","description":"`true` when the location may be out of date."},"tracker_label":{"type":"string","description":"Label of the related tracker."},"emergency":{"type":"boolean","description":"`true` for an emergency event, matching the same flag on the rule."},"zone_ids":{"type":"array","description":"Related geofence IDs.","items":{"type":"integer"}},"zone_labels":{"type":"array","description":"Related geofence labels.","items":{"type":"string"}},"proximity_object_id":{"type":"integer","description":"ID of the tracker involved in a proximity event."},"employee_id":{"type":"integer","description":"ID of the driver at the time of the event."},"sensor_id":{"type":"integer","description":"Related sensor ID."},"sensor_name":{"type":"string","description":"Related sensor name."},"sensor_calculated_value":{"type":"string","description":"Related sensor value."},"full_message":{"type":"string","description":"The full event message, present when `message` was shortened."},"precision":{"type":"integer","description":"Precision of the location in metres."},"command":{"type":"object","description":"Present on a `command_sent` event: a command dispatched from a tracker's Commands block.","properties":{"name":{"type":"string","description":"Name of the command that was sent."},"param":{"type":["string","null"],"description":"Value substituted for the command's `<>` placeholder, when it has one."},"response":{"type":"object","description":"Delivery result. A `hardware` command populates only `success`; an `http` command populates `status` and `body` (and `error` in place of them when the request itself failed) instead, leaving `success` absent.","properties":{"status":{"type":["integer","null"],"description":"HTTP status code returned by the destination endpoint. Present only for an `http` command."},"body":{"type":["string","null"],"description":"Raw response body from the destination endpoint, truncated to fit the event's storage limit. Present only for an `http` command."},"error":{"type":["string","null"],"description":"Error message, up to 256 characters, when the request to the destination endpoint could not be completed. Present only for an `http` command, and only when the request failed."},"success":{"type":["boolean","null"],"description":"Whether the command was sent to the device. Present only for a `hardware` command."}}}}}},"additionalProperties":true}}}},"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":{"/history/read":{"post":{"tags":["History"],"summary":"Read history entry","description":"Return one history entry by ID.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"historyRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the history entry.","minimum":1,"format":"int64"},"add_tracker_label":{"type":"boolean","description":"Optional. Add the tracker label to the `message` field."}},"required":["id"]}}}},"responses":{"200":{"description":"The history entry","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"$ref":"#/components/schemas/HistoryEntry"}}}}}},"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"},"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.

***

## Mark history entry read

> Mark one history entry as read, setting its \`is\_read\` to \`true\`.\
> \
> 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":"History","description":"The events history: what happened on trackers and assets, what the account itself did, and which entries the user has read. All resources under the /history/ 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"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"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":{"/history/mark_read":{"post":{"tags":["History"],"summary":"Mark history entry read","description":"Mark one history entry as read, setting its `is_read` to `true`.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"historyMarkRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"ID of the history entry to mark read.","minimum":1}},"required":["id"]}}}},"responses":{"200":{"description":"Entry marked read","$ref":"#/components/responses/OK"},"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"},"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.

***

## Mark all history read

> Mark \*\*every\*\* unread history entry as read.\
> \
> This takes no parameters and cannot be undone: there is no operation to mark an entry unread again. An empty request body is a complete, valid call, so it will act on the whole account.\
> \
> Also accepts GET.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"History","description":"The events history: what happened on trackers and assets, what the account itself did, and which entries the user has read. All resources under the /history/ 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"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"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":{"/history/mark_read_all":{"post":{"tags":["History"],"summary":"Mark all history read","description":"Mark **every** unread history entry as read.\n\nThis takes no parameters and cannot be undone: there is no operation to mark an entry unread again. An empty request body is a complete, valid call, so it will act on the whole account.\n\nAlso accepts GET.","operationId":"historyMarkReadAll","responses":{"200":{"description":"All entries marked read","$ref":"#/components/responses/OK"},"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"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

## More in this section

#### Tracker events

| Endpoint                                                                                                                    | Method | What it does         |
| --------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------- |
| [`/history/tracker/list`](/docs/navixy-api/user-api/resources/commons/history/history_tracker.md#post-history-tracker-list) | POST   | List tracker history |

#### Event type

| Endpoint                                                                                                           | Method | What it does             |
| ------------------------------------------------------------------------------------------------------------------ | ------ | ------------------------ |
| [`/history/type/list`](/docs/navixy-api/user-api/resources/commons/history/history_type.md#post-history-type-list) | POST   | List history event types |

#### Unread events

| Endpoint                                                                                                                   | Method | What it does         |
| -------------------------------------------------------------------------------------------------------------------------- | ------ | -------------------- |
| [`/history/unread/list`](/docs/navixy-api/user-api/resources/commons/history/history_unread.md#post-history-unread-list)   | POST   | List unread history  |
| [`/history/unread/count`](/docs/navixy-api/user-api/resources/commons/history/history_unread.md#post-history-unread-count) | POST   | Count unread history |

#### User events

| Endpoint                                                                                                           | Method | What it does      |
| ------------------------------------------------------------------------------------------------------------------ | ------ | ----------------- |
| [`/history/user/list`](/docs/navixy-api/user-api/resources/commons/history/history-user.md#post-history-user-list) | POST   | List user history |

#### Asset events

| Endpoint                                                                                                               | Method | What it does        |
| ---------------------------------------------------------------------------------------------------------------------- | ------ | ------------------- |
| [`/history/asset/list`](/docs/navixy-api/user-api/resources/commons/history/asset-events.md#post-history-asset-list)   | POST   | List asset history  |
| [`/history/asset/count`](/docs/navixy-api/user-api/resources/commons/history/asset-events.md#post-history-asset-count) | POST   | Count asset history |


---

# 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/commons/history.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.