Case history

Case history API

Every case keeps an audit log of its lifecycle events, such as when the case was created, its status or owner changed, or a chat activity was linked to it. Each event is stored as a case history entry.

Case history entries have the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The unique identifier of this history entry
case_id	UUID	read-only	ID of the case this entry belongs to
case_number		read-only	Human-readable identifier for the case, unique within the organization. Automatically generated when the case is created, in the format -, e.g. CASE-XK7M9DWE.
event_type	string	read-only	Type of the event. See the list of event types below.
description	string	read-only	Human-readable description of the event
metadata	object	read-only	Additional structured details about the event, or null. The contents depend on the event type, e.g. {"from_status": "open", "to_status": "closed"} for a status change.
created_at	datetime	read-only	When the event occurred, in ISO 8601 format
created_by_user_id	UUID	read-only	ID of the user who triggered the event, or null if the event was triggered automatically
created_by_user	object	read-only	The user who triggered the event as a nested object, or null if the event was triggered automatically

The possible values for event_type, and the metadata contents for each of them, are:

Event type	Description	Metadata
case_created	The case was created	null
case_closed	The case was closed	null
status_changed	The status of the case was changed	from_status, to_status
owner_changed	The owner of the case was changed	from_owner_id, to_owner_id
priority_changed	The priority of the case was changed	from_priority, to_priority
stage_changed	The case was moved to a funnel stage	case_funnel_id, to_stage_id, and from_stage_id when the case moved from another stage (absent when the case was first added to the funnel)
activity_added	An activity (chat) was linked to the case	chat_id
activity_removed	An activity (chat) was unlinked from the case	chat_id
case_auto_closed_stage	The case was automatically closed by entering a funnel stage	case_funnel_id, from_stage_id, to_stage_id, trigger
case_auto_reopened_stage	The case was automatically reopened by entering a funnel stage	case_funnel_id, from_stage_id, to_stage_id, trigger
case_chats_auto_closed	The chats of the case were automatically closed by a funnel rule	chat_ids
bulk_edit	The case was updated as part of a bulk edit	fields

The metadata fields are:

Field	Type	Description
from_status / to_status	string	The case status before and after the change, e.g. "open", "closed"
from_owner_id / to_owner_id	UUID	The owner user ID before and after the change. Either may be null when the owner was assigned for the first time or unassigned.
from_priority / to_priority	string	The case priority before and after the change
case_funnel_id	UUID	ID of the case funnel involved in the stage change
from_stage_id / to_stage_id	UUID	ID of the funnel stage the case moved from and to. from_stage_id may be null for auto close/reopen events when the previous stage is not known.
trigger	string	What triggered the automatic close/reopen. Currently always "stage_transition".
chat_id	UUID	ID of the chat that was linked to or unlinked from the case
chat_ids	array of UUIDs	IDs of the chats that were automatically closed
fields	array of strings	Names of the case fields that were updated in the bulk edit, e.g. ["owner_id", "priority"]

List case history entries

You can list all history entries of a single case:

GET /api/v5/orgs/<organization_id>/cases/<case_id>/history

This API endpoint returns a paginated collection of case history entries, sorted by the most recent entry first.

The endpoint supports the following GET parameters:

Parameter	Type	Default	Description
event_type	string	—	Only return entries with the given event type, e.g. status_changed
ordering	string	-created_at	Sorting order of the entries. Either created_at (oldest first) or -created_at (newest first).
cursor	string	—	Pagination cursor from the next or previous URL of a previous response

The endpoint returns these status codes:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 404 if the case does not exist in the organization

Example response:

{
  "next": "https://service.giosg.com/api/v5/orgs/4a5d1f77-63a1-4b21-9d92-cbc3bf7c34e1/cases/8a0f77a3-84b9-4b39-9821-3e17adf7d446/history?cursor=cD0yMDI2LTA4LTIxKzA5JTNBMTQlM0EwMi4xMjM0NTYlMkIwMCUzQTAw",
  "previous": null,
  "results": [
    {
      "id": "f3b0a1de-59c9-4bfa-9c3a-6a1cf1f7f0b2",
      "case_id": "8a0f77a3-84b9-4b39-9821-3e17adf7d446",
      "case_number": "CASE-XK7M9DWE",
      "event_type": "status_changed",
      "description": "Status changed from open to closed",
      "metadata": {
        "from_status": "open",
        "to_status": "closed"
      },
      "created_at": "2026-08-21T09:14:02.123456Z",
      "created_by_user_id": "9b19f5a2-31b4-4b7d-8c1b-05f7c2a2b111",
      "created_by_user": {
        "id": "9b19f5a2-31b4-4b7d-8c1b-05f7c2a2b111",
        "first_name": "John",
        "last_name": "Smith",
        "full_name": "John Smith",
        "organization_id": "4a5d1f77-63a1-4b21-9d92-cbc3bf7c34e1",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false,
        "is_staff": false
      }
    },
    {
      "id": "0d5c7c39-2d0e-4d43-b8a3-1f1b1a2c3d4e",
      "case_id": "8a0f77a3-84b9-4b39-9821-3e17adf7d446",
      "case_number": "CASE-XK7M9DWE",
      "event_type": "case_created",
      "description": "Case created",
      "metadata": null,
      "created_at": "2026-08-20T14:03:45.000000Z",
      "created_by_user_id": "9b19f5a2-31b4-4b7d-8c1b-05f7c2a2b111",
      "created_by_user": {
        "id": "9b19f5a2-31b4-4b7d-8c1b-05f7c2a2b111",
        "first_name": "John",
        "last_name": "Smith",
        "full_name": "John Smith",
        "organization_id": "4a5d1f77-63a1-4b21-9d92-cbc3bf7c34e1",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false,
        "is_staff": false
      }
    }
  ]
}