# State Transition Logs
State change history and audit trail
## List state transition logs
> Returns a paginated list of state transition logs with comprehensive filtering options.\
> \
> This endpoint provides audit trail information for all state changes in the system.\
> Logs are automatically created whenever an object (Package, TransferOrder, etc.) \
> transitions from one state to another.\
> \
> \*\*Note:\*\* This is a read-only resource. Logs cannot be created, updated, or deleted via the API.
```json
{"openapi":"3.0.3","info":{"title":"OMS States Module API","version":"1.0.0"},"tags":[{"name":"state-transition-logs","description":"State change history and audit trail"}],"servers":[{"url":"https://{domain}/api/v1/oms","variables":{"domain":{"default":"domain.akinon.com"}}}],"security":[{"OmnitronPermission":[]}],"components":{"securitySchemes":{"OmnitronPermission":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication required for all endpoints.\n\nInclude the token in the Authorization header:\n`Authorization: Bearer `\n"}},"parameters":{"format":{"name":"format","in":"query","description":"Response format (json, xml, etc.)","schema":{"type":"string","default":"json","enum":["json","xml"]}},"page":{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":"integer","default":1,"minimum":1}},"limit":{"name":"limit","in":"query","description":"Number of items per page","schema":{"type":"integer","default":10,"minimum":1,"maximum":100}},"sort":{"name":"sort","in":"query","description":"Sort results by field. Prefix with '-' for descending order.\n\nAvailable sort fields:\n- `id` or `-id`\n- `created_date` or `-created_date`\n- `modified_date` or `-modified_date`\n","schema":{"type":"string","default":"-id"}},"oldState":{"name":"old_state","in":"query","description":"Filter by old state ID","schema":{"type":"integer"}},"newState":{"name":"new_state","in":"query","description":"Filter by new state ID","schema":{"type":"integer"}},"oldStateName":{"name":"old_state__name","in":"query","description":"Filter by old state name (exact match)","schema":{"type":"string"}},"newStateName":{"name":"new_state__name","in":"query","description":"Filter by new state name (exact match)","schema":{"type":"string"}},"oldStateEnumValueIn":{"name":"old_state__enum_value__in","in":"query","description":"Filter by old state enum values (comma-separated list)","schema":{"type":"string"}},"newStateEnumValueIn":{"name":"new_state__enum_value__in","in":"query","description":"Filter by new state enum values (comma-separated list)","schema":{"type":"string"}},"objectId":{"name":"object_id","in":"query","description":"Filter by related object ID","schema":{"type":"integer"}},"contentType":{"name":"content_type","in":"query","description":"Filter by content type ID","schema":{"type":"integer"}},"createdDateGt":{"name":"created_date__gt","in":"query","description":"Filter logs created after this date","schema":{"type":"string","format":"date-time"}},"createdDateGte":{"name":"created_date__gte","in":"query","description":"Filter logs created on or after this date","schema":{"type":"string","format":"date-time"}},"createdDateLt":{"name":"created_date__lt","in":"query","description":"Filter logs created before this date","schema":{"type":"string","format":"date-time"}},"createdDateLte":{"name":"created_date__lte","in":"query","description":"Filter logs created on or before this date","schema":{"type":"string","format":"date-time"}},"modifiedDateGt":{"name":"modified_date__gt","in":"query","description":"Filter logs modified after this date","schema":{"type":"string","format":"date-time"}},"modifiedDateGte":{"name":"modified_date__gte","in":"query","description":"Filter logs modified on or after this date","schema":{"type":"string","format":"date-time"}},"modifiedDateLt":{"name":"modified_date__lt","in":"query","description":"Filter logs modified before this date","schema":{"type":"string","format":"date-time"}},"modifiedDateLte":{"name":"modified_date__lte","in":"query","description":"Filter logs modified on or before this date","schema":{"type":"string","format":"date-time"}},"idGt":{"name":"id__gt","in":"query","description":"Filter by ID greater than","schema":{"type":"integer"}},"idGte":{"name":"id__gte","in":"query","description":"Filter by ID greater than or equal to","schema":{"type":"integer"}},"idLt":{"name":"id__lt","in":"query","description":"Filter by ID less than","schema":{"type":"integer"}},"idLte":{"name":"id__lte","in":"query","description":"Filter by ID less than or equal to","schema":{"type":"integer"}}},"schemas":{"StateTransitionLog":{"type":"object","description":"Represents a state transition log entry with complete nested relationship data.\n\nThis schema includes full details of the old state, new state, and user who triggered\nthe transition. The attributes field contains additional metadata about the transition.\n","properties":{"id":{"type":"integer","description":"Unique identifier for the log entry","readOnly":true},"old_state":{"$ref":"#/components/schemas/StateListSerializer"},"new_state":{"$ref":"#/components/schemas/StateListSerializer"},"user":{"$ref":"#/components/schemas/UserListSerializer","nullable":true},"attributes":{"type":"object","description":"Additional metadata about the state transition.\n\nCommon fields:\n- `command.slug`: The command that triggered the transition (e.g., \"PKG_STATE_TRANSITION\")\n- `command.transition_id`: The ID of the state transition rule used\n- `remote_user_pk`: The ID of the user in a remote system\n- `remote_user_mail`: The email of the user in a remote system\n","nullable":true},"created_date":{"type":"string","format":"date-time","description":"When the transition occurred","readOnly":true},"object_id":{"type":"integer","description":"ID of the object that transitioned (Package, TransferOrder, etc.)","readOnly":true},"content_type":{"type":"integer","description":"Content type ID identifying the type of object that transitioned","readOnly":true}},"required":["id","old_state","new_state","created_date","object_id","content_type"]},"StateListSerializer":{"type":"object","description":"Represents a state with basic information","properties":{"id":{"type":"integer","description":"Unique identifier for the state"},"name":{"type":"string","description":"Human-readable name of the state"},"enum_value":{"type":"string","description":"Numeric enum value as string"},"enum_class":{"type":"string","description":"Name of the enum class"}},"required":["id","name","enum_value","enum_class"]},"UserListSerializer":{"type":"object","description":"Represents a user with basic information","properties":{"pk":{"type":"integer","description":"User's primary key"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"username":{"type":"string","description":"User's username"}},"required":["pk","username"]},"Error":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong"},"errors":{"type":"object","description":"Field-specific errors (for validation errors)","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/state-transition-logs/":{"get":{"tags":["state-transition-logs"],"summary":"List state transition logs","description":"Returns a paginated list of state transition logs with comprehensive filtering options.\n\nThis endpoint provides audit trail information for all state changes in the system.\nLogs are automatically created whenever an object (Package, TransferOrder, etc.) \ntransitions from one state to another.\n\n**Note:** This is a read-only resource. Logs cannot be created, updated, or deleted via the API.\n","operationId":"listStateTransitionLogs","parameters":[{"$ref":"#/components/parameters/format"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/oldState"},{"$ref":"#/components/parameters/newState"},{"$ref":"#/components/parameters/oldStateName"},{"$ref":"#/components/parameters/newStateName"},{"$ref":"#/components/parameters/oldStateEnumValueIn"},{"$ref":"#/components/parameters/newStateEnumValueIn"},{"$ref":"#/components/parameters/objectId"},{"$ref":"#/components/parameters/contentType"},{"$ref":"#/components/parameters/createdDateGt"},{"$ref":"#/components/parameters/createdDateGte"},{"$ref":"#/components/parameters/createdDateLt"},{"$ref":"#/components/parameters/createdDateLte"},{"$ref":"#/components/parameters/modifiedDateGt"},{"$ref":"#/components/parameters/modifiedDateGte"},{"$ref":"#/components/parameters/modifiedDateLt"},{"$ref":"#/components/parameters/modifiedDateLte"},{"$ref":"#/components/parameters/idGt"},{"$ref":"#/components/parameters/idGte"},{"$ref":"#/components/parameters/idLt"},{"$ref":"#/components/parameters/idLte"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of state transition logs"},"next":{"type":"string","nullable":true,"description":"URL to the next page of results"},"previous":{"type":"string","nullable":true,"description":"URL to the previous page of results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/StateTransitionLog"}}}}}}},"400":{"description":"Bad request - invalid filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get state transition log by ID
> Retrieve a specific state transition log entry by its ID.\
> \
> Returns detailed information about a single state change including the old state,\
> new state, user who triggered the change, and additional metadata in the attributes field.
```json
{"openapi":"3.0.3","info":{"title":"OMS States Module API","version":"1.0.0"},"tags":[{"name":"state-transition-logs","description":"State change history and audit trail"}],"servers":[{"url":"https://{domain}/api/v1/oms","variables":{"domain":{"default":"domain.akinon.com"}}}],"security":[{"OmnitronPermission":[]}],"components":{"securitySchemes":{"OmnitronPermission":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication required for all endpoints.\n\nInclude the token in the Authorization header:\n`Authorization: Bearer `\n"}},"parameters":{"format":{"name":"format","in":"query","description":"Response format (json, xml, etc.)","schema":{"type":"string","default":"json","enum":["json","xml"]}}},"schemas":{"StateTransitionLog":{"type":"object","description":"Represents a state transition log entry with complete nested relationship data.\n\nThis schema includes full details of the old state, new state, and user who triggered\nthe transition. The attributes field contains additional metadata about the transition.\n","properties":{"id":{"type":"integer","description":"Unique identifier for the log entry","readOnly":true},"old_state":{"$ref":"#/components/schemas/StateListSerializer"},"new_state":{"$ref":"#/components/schemas/StateListSerializer"},"user":{"$ref":"#/components/schemas/UserListSerializer","nullable":true},"attributes":{"type":"object","description":"Additional metadata about the state transition.\n\nCommon fields:\n- `command.slug`: The command that triggered the transition (e.g., \"PKG_STATE_TRANSITION\")\n- `command.transition_id`: The ID of the state transition rule used\n- `remote_user_pk`: The ID of the user in a remote system\n- `remote_user_mail`: The email of the user in a remote system\n","nullable":true},"created_date":{"type":"string","format":"date-time","description":"When the transition occurred","readOnly":true},"object_id":{"type":"integer","description":"ID of the object that transitioned (Package, TransferOrder, etc.)","readOnly":true},"content_type":{"type":"integer","description":"Content type ID identifying the type of object that transitioned","readOnly":true}},"required":["id","old_state","new_state","created_date","object_id","content_type"]},"StateListSerializer":{"type":"object","description":"Represents a state with basic information","properties":{"id":{"type":"integer","description":"Unique identifier for the state"},"name":{"type":"string","description":"Human-readable name of the state"},"enum_value":{"type":"string","description":"Numeric enum value as string"},"enum_class":{"type":"string","description":"Name of the enum class"}},"required":["id","name","enum_value","enum_class"]},"UserListSerializer":{"type":"object","description":"Represents a user with basic information","properties":{"pk":{"type":"integer","description":"User's primary key"},"first_name":{"type":"string","description":"User's first name"},"last_name":{"type":"string","description":"User's last name"},"email":{"type":"string","format":"email","description":"User's email address"},"username":{"type":"string","description":"User's username"}},"required":["pk","username"]},"Error":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong"},"errors":{"type":"object","description":"Field-specific errors (for validation errors)","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/state-transition-logs/{id}/":{"get":{"tags":["state-transition-logs"],"summary":"Get state transition log by ID","description":"Retrieve a specific state transition log entry by its ID.\n\nReturns detailed information about a single state change including the old state,\nnew state, user who triggered the change, and additional metadata in the attributes field.\n","operationId":"retrieveStateTransitionLog","parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the state transition log","schema":{"type":"integer"}},{"$ref":"#/components/parameters/format"}],"responses":{"200":{"description":"State transition log details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateTransitionLog"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"State transition log not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List state transition logs (simple format)
> Returns a list of state transition logs with minimal information without nested serializers.\
> \
> This endpoint is useful for lightweight data retrieval when nested relationship data is not needed.\
> Foreign key fields return only IDs instead of full nested objects, reducing response payload size.\
> \
> \*\*Note:\*\* This endpoint does not use pagination by default.
```json
{"openapi":"3.0.3","info":{"title":"OMS States Module API","version":"1.0.0"},"tags":[{"name":"state-transition-logs","description":"State change history and audit trail"}],"servers":[{"url":"https://{domain}/api/v1/oms","variables":{"domain":{"default":"domain.akinon.com"}}}],"security":[{"OmnitronPermission":[]}],"components":{"securitySchemes":{"OmnitronPermission":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication required for all endpoints.\n\nInclude the token in the Authorization header:\n`Authorization: Bearer `\n"}},"parameters":{"format":{"name":"format","in":"query","description":"Response format (json, xml, etc.)","schema":{"type":"string","default":"json","enum":["json","xml"]}},"sort":{"name":"sort","in":"query","description":"Sort results by field. Prefix with '-' for descending order.\n\nAvailable sort fields:\n- `id` or `-id`\n- `created_date` or `-created_date`\n- `modified_date` or `-modified_date`\n","schema":{"type":"string","default":"-id"}},"oldState":{"name":"old_state","in":"query","description":"Filter by old state ID","schema":{"type":"integer"}},"newState":{"name":"new_state","in":"query","description":"Filter by new state ID","schema":{"type":"integer"}},"objectId":{"name":"object_id","in":"query","description":"Filter by related object ID","schema":{"type":"integer"}},"contentType":{"name":"content_type","in":"query","description":"Filter by content type ID","schema":{"type":"integer"}},"createdDateGte":{"name":"created_date__gte","in":"query","description":"Filter logs created on or after this date","schema":{"type":"string","format":"date-time"}},"createdDateLte":{"name":"created_date__lte","in":"query","description":"Filter logs created on or before this date","schema":{"type":"string","format":"date-time"}}},"schemas":{"StateTransitionLogSimple":{"type":"object","description":"Simplified state transition log entry without nested relationship data.\nForeign key fields return only IDs for lightweight data retrieval.\n","properties":{"id":{"type":"integer","description":"Unique identifier for the log entry"},"created_date":{"type":"string","format":"date-time","description":"When the transition occurred"},"modified_date":{"type":"string","format":"date-time","description":"When the log entry was last modified"},"old_state":{"type":"integer","description":"ID of the old state"},"new_state":{"type":"integer","description":"ID of the new state"},"content_type":{"type":"integer","description":"Content type ID"},"object_id":{"type":"integer","description":"ID of the object that transitioned"},"user":{"type":"integer","nullable":true,"description":"ID of the user who triggered the transition"},"attributes":{"type":"object","nullable":true,"description":"Additional metadata about the transition"}}},"Error":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong"},"errors":{"type":"object","description":"Field-specific errors (for validation errors)","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/state-transition-logs/simple/":{"get":{"tags":["state-transition-logs"],"summary":"List state transition logs (simple format)","description":"Returns a list of state transition logs with minimal information without nested serializers.\n\nThis endpoint is useful for lightweight data retrieval when nested relationship data is not needed.\nForeign key fields return only IDs instead of full nested objects, reducing response payload size.\n\n**Note:** This endpoint does not use pagination by default.\n","operationId":"listSimpleStateTransitionLogs","parameters":[{"$ref":"#/components/parameters/format"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/oldState"},{"$ref":"#/components/parameters/newState"},{"$ref":"#/components/parameters/objectId"},{"$ref":"#/components/parameters/contentType"},{"$ref":"#/components/parameters/createdDateGte"},{"$ref":"#/components/parameters/createdDateLte"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StateTransitionLogSimple"}}}}},"400":{"description":"Bad request - invalid filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions: 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:
```
GET https://apidocs.akinon.com/oms-openapis/state/state-transition-logs.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.