> 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/history-user.md). # User events The account's own event history, as opposed to a tracker's. This operation reads the [event history](/docs/navixy-api/user-api/resources/commons/history.md) of the account itself: what its users did, rather than what its devices did. {% hint style="info" %} A request with an empty body reports `interval` as the missing parameter. There is no such parameter. It is the internal name of the field holding both dates, and the public parameters are `from` and `to`. {% endhint %} ## API actions API base path: `/history/user`. At most one label is added to `message`, as `label: message`. With `add_asset_label` on, an entry naming a vehicle or an employee takes the asset label, which is the vehicle label or, when there is no vehicle, the employee's full name. An entry naming neither falls back to the tracker label, even with `add_tracker_label` off. *** ## List user history > Return the account's own event history over a period, as opposed to the history of a particular tracker.\ > \ > \*\*Only one label is ever prefixed to \`message\`, as \`label: message\`.\*\* With \`add\_asset\_label\` on, an entry naming a vehicle or an employee takes the asset label, which is the vehicle label or, when there is no vehicle, the employee's full name. An entry naming neither falls back to the tracker label, even with \`add\_tracker\_label\` off. With \`add\_asset\_label\` off, \`add\_tracker\_label\` decides on its own.\ > \ > A request with an empty body reports \`interval\` as the missing parameter. That is the internal name of the field holding both dates; the public parameters are \`from\` and \`to\`. ```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/user/list":{"post":{"tags":["History"],"summary":"List user history","description":"Return the account's own event history over a period, as opposed to the history of a particular tracker.\n\n**Only one label is ever prefixed to `message`, as `label: message`.** With `add_asset_label` on, an entry naming a vehicle or an employee takes the asset label, which is the vehicle label or, when there is no vehicle, the employee's full name. An entry naming neither falls back to the tracker label, even with `add_tracker_label` off. With `add_asset_label` off, `add_tracker_label` decides on its own.\n\nA request with an empty body reports `interval` as the missing parameter. That is the internal name of the field holding both dates; the public parameters are `from` and `to`.","operationId":"historyUserList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Start of the period. Include events recorded at or after this date."},"to":{"type":"string","description":"End of the period. Include events recorded at or before this date. Must be after `from`."},"events":{"type":"array","description":"Optional. Restrict to these event types. Available types come from `history/type/list`.","items":{"type":"string"}},"limit":{"type":"integer","description":"Optional. Defaults to the platform `history.max_limit`, which `dealer/get_ui_config` reports. Maximum number of records to return."},"ascending":{"type":"boolean","description":"Optional. Default `true`. Order by time ascending, or descending when `false`."},"only_emergency":{"type":"boolean","description":"Optional. Default `false`. Include only emergency events."},"only_unread":{"type":"boolean","description":"Optional. Default `false`. Include only unread events."},"add_asset_label":{"type":"boolean","description":"Optional. Default `false`. Add the asset label to the `message` field."},"add_tracker_label":{"type":"boolean","description":"Optional. Default `true`. Add the tracker label to the `message` field."},"add_tracker_files":{"type":"boolean","description":"Optional. Default `false`. Include tracker file information. Honoured only for a caller holding the `video_monitoring` right, and ignored otherwise."}},"required":["from","to"]}}}},"responses":{"200":{"description":"Matching history entries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEntry"}},"limit_exceeded":{"type":"boolean","description":"`true` when the result was cut short by the platform limit, so more entries match than were returned. There is no total count: use the matching `count` operation for that."}}}}}},"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"},"403":{"description":"Error 211: the requested time span is too big. Error 212: the requested period is not available on the current plan.","$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): * 211 - Requested time span is too big. * 212 - Requested period is not available on the current plan. --- # 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/history-user.md?ask=&goal= ``` `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.