---
title: List
url: https://www.tines.com/docs/api/cases/list/
updated: 2026-05-26T15:26:21+00:00
description: Retrieve a list of cases.
---
*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Tines API](https://www.tines.com/llms.txt) › [Cases](https://www.tines.com/llm/docs/api/cases.md)*
# List
*[View on tines.com](https://www.tines.com/docs/api/cases/list/)*
## Description
Retrieve a list of cases.
## Request
HTTP Method: **GET**
| Query Parameter | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| team_id | **Optional** Retrieve cases for the specified team. |
| filters | **Optional** Object specifying case filters (see the table below). |
| order | **Optional** `RECENTLY_EDITED`, `LEAST_RECENTLY_EDITED`, `PRIORITY_ASC`, `PRIORITY_DESC`, `OPENED_ASC`, `OPENED_DESC`, `CREATED_ASC` or `CREATED_DESC`. |
| per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. |
| page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. |
Supported parameters in `filters`
| `filters` parameters | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assignee filters** | |
| assignees | **Optional** A single user ID, email address, the string `"unassigned"`, or an array of these values. Cases matching any of the specified assignees will be returned. Use `"unassigned"` to filter for cases with no assignees. |
| and_assignees | **Optional** A single user ID or an array of user IDs. Cases must have all specified assignees (AND logic). |
| exclude_assignees | **Optional** A single user ID or an array of user IDs to exclude. Cases with any of the specified assignees will be excluded. |
| assigned_to_me | **Optional** A boolean (true or false). Filter cases assigned to the current user. |
| assignee_emails | **Optional** A single email address or an array of user email addresses. **Deprecated**: Use `assignees` with email addresses instead. |
| unassigned | **Optional** A boolean (true or false). **Deprecated**: Use `assignees: ["unassigned"]` instead. |
| **Author filters** | |
| authors | **Optional** A single author user ID, email address, the string `"tines"`, or an array of these values. Cases created by any of the specified authors will be returned. Use `"tines"` to filter for cases created via automation. |
| exclude_authors | **Optional** A single author user ID or an array of author user IDs to exclude. Cases created by any of the specified authors will be excluded. |
| author_emails | **Optional** A single email address or an array of author emails. **Deprecated**: Use `authors` with email addresses instead. |
| **Tag filters** | |
| tags | **Optional** A single tag name or an array of tag names (behaves the same as `and_tags`). Cases must have all specified tags. |
| and_tags | **Optional** A single tag name or an array of tag names to AND'd by. Cases must have all specified tags. |
| or_tags | **Optional** A single tag name or an array of tag names that are OR'd by. Cases matching any of the specified tags will be returned. |
| exclude_tags | **Optional** A single tag name or an array of tag names to exclude by. Cases with any of the specified tags will be excluded. |
| **Priority filters** | |
| priority | **Optional** A single priority or an array of priorities. Valid values: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`. Cases matching any of the specified priorities will be returned. |
| exclude_priorities | **Optional** A single priority or an array of priorities to exclude. Valid values: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`. |
| **Status filters** | |
| status | **Optional** `OPEN` or `CLOSED`. |
| sub_status_names | **Optional** A single sub status name or an array of sub status names. Cases matching any of the specified sub statuses will be returned. |
| exclude_sub_status_names | **Optional** A single sub status name or an array of sub status names to exclude. |
| **Metadata filters** | |
| metadata | **Optional** A single metadata object or an array of metadata objects. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Uses AND logic (same as `and_metadata`). |
| and_metadata | **Optional** A single metadata object or an array of metadata objects using AND logic. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Cases must match all specified metadata entries. |
| or_metadata | **Optional** A single metadata object or an array of metadata objects using OR logic. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Cases matching any of the specified metadata entries will be returned. |
| **Field filters** | |
| fields | **Optional** A single field object or an array of field objects to filter by case input values. Each field object contains:
• `key`: The slug of the case input field (e.g., `<>` for a "Host name" field)
• `value`: The value to search for. Uses AND logic (same as `and_fields`). |
| and_fields | **Optional** A single field object or an array of field objects to filter by case input values using AND logic. Each field object contains:
• `key`: The slug of the case input field
• `value`: The value to search for. Cases must match all specified fields. |
| or_fields | **Optional** A single field object or an array of field objects to filter by case input values using OR logic. Each field object contains:
• `key`: The slug of the case input field
• `value`: The value to search for. Cases matching any of the specified fields will be returned. |
| **Date filters** | |
| start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases created on or after this date. |
| end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases created before or on this date. |
| relative_date | **Optional** A string specifying a relative date range. Valid values:
• `"today"` - Cases created today
• `"yesterday"` - Cases created yesterday
• `"X days"` or `"X day"` - Cases created in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases created in the last X weeks (e.g., `"2 weeks"`)
• `"X months"` or `"X month"` - Cases created in the last X months (e.g., `"1 month"`)
• `"X years"` or `"X year"` - Cases created in the last X years (e.g., `"1 year"`)
Filters cases by creation date. |
| time_range | **Optional** A string specifying a time range filter in 24-hour format: `"HH:MM-HH:MM"` (e.g., `"09:00-17:00"`). If the start time is greater than the end time (e.g., `"22:00-06:00"`), it spans midnight. Filters cases by creation time within the specified range. |
| resolved_at_start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases resolved on or after this date. |
| resolved_at_end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases resolved before or on this date. |
| resolved_at_relative_date | **Optional** A string specifying a relative date range for resolved date. Valid values:
• `"today"` - Cases resolved today
• `"yesterday"` - Cases resolved yesterday
• `"X days"` or `"X day"` - Cases resolved in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases resolved in the last X weeks
• `"X months"` or `"X month"` - Cases resolved in the last X months
• `"X years"` or `"X year"` - Cases resolved in the last X years |
| updated_at_start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases updated on or after this date. |
| updated_at_end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases updated before or on this date. |
| updated_at_relative_date | **Optional** A string specifying a relative date range for updated date. Valid values:
• `"today"` - Cases updated today
• `"yesterday"` - Cases updated yesterday
• `"X days"` or `"X day"` - Cases updated in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases updated in the last X weeks
• `"X months"` or `"X month"` - Cases updated in the last X months
• `"X years"` or `"X year"` - Cases updated in the last X years |
| **SLA filters** | |
| sla_status | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases matching any of the specified SLA statuses will be returned (OR logic). |
| and_sla_status | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases must match all specified SLA statuses (AND logic). |
| exclude_sla_status | **Optional** A single SLA status or an array of SLA statuses to exclude. Valid values: `warning`, `exceeded`. Cases with any of the specified SLA statuses will be excluded. |
| sla_type | **Optional** A single SLA type or an array of SLA types. Valid values: `resolution`, `response`. Cases matching any of the specified SLA types will be returned (OR logic). |
| and_sla_type | **Optional** A single SLA type or an array of SLA types. Valid values: `resolution`, `response`. Cases must match all specified SLA types (AND logic). |
| exclude_sla_type | **Optional** A single SLA type or an array of SLA types to exclude. Valid values: `resolution`, `response`. Cases with any of the specified SLA types will be excluded. |
| sla | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases matching any of the specified SLA statuses will be returned (OR logic). **Deprecated**: Use `sla_status` instead. |
| **Text search filters** | |
| search | **Optional** A string that searches against case name, description and ID. |
| name | **Optional** A string that searches against case name. |
| comment | **Optional** A string that searches against case comments. |
| note | **Optional** A string that searches against case notes. |
| **Other filters** | |
| case_ids | **Optional** A single case ID or an array of case IDs. |
| child_team_ids | **Optional** A single child team ID or an array of child team IDs. Filter cases belonging to the specified teams. |
| records | **Optional** A single record result value or an array of record result values (strings). Cases containing a record matching any of the results provided will be returned. Note: Large text record fields are not queryable in this instance. |
| subscribed | **Optional** A boolean (true or false). Filter cases the current user is subscribed to. |
| my_open_tasks | **Optional** A boolean (true or false). Filter cases that have open tasks assigned to the current user. |
```bash
curl -X GET \
https:///api/v2/cases \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <>'
```
### Example request with search filters
Sample request params:
```json
{
"team_id": "1",
"filters": {
"search": "Sample search string",
"status": "OPEN",
"priority": ["HIGH", "CRITICAL"],
"fields": [
{
"key": "company",
"value": "Tines"
}
]
},
"order": "OPENED_DESC",
"per_page": "10"
}
```
Example request:
```bash
curl -v \
-X GET \
--location \
"https:///api/v2/cases/?order=OPENED_DESC&per_page=10&team_id=1" \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <>' \
--data '{
"filters": {
"status": "OPEN",
"priority": ["HIGH", "CRITICAL"],
"fields": [
{
"key": "version",
"value": "2.0"
}
]
}
}'
```
## Response
A successful request will return a JSON object containing the cases the requesting token has access to.
### Field description
| Parameter | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| case_id | The ID of the case. |
| name | The case name. |
| description | The case description. |
| status | The case status - open or closed. |
| sub_status | An object describing the case sub-status. |
| url | The case URL. |
| metadata | Case related metadata represented as key-value pairs. |
| author | An object describing the case author. |
| opened_by | An object describing the user who opened the case. |
| resolved_by | An object describing the user who resolved the case. |
| assignees | An array of users assigned to the case. |
| tags | An array of tags associated with the case. |
| fields | An array of field values for the case. |
| activities | An array of team case actions taken within the case. |
| activities_meta | Metadata defining pagination params required to fetch additional activities for the case. |
| linked_cases_meta | Metadata defining pagination params required to fetch additional linked cases for the case. |
| team | The team the case is within - ID & name. |
| actions | An array of case actions for downstream actions associated with the case. |
| linked_cases | An array of cases linked to this case - ID & name. |
| sla | An object describing the case SLA status. Times are in seconds. |
| slas | An array of SLAs for the case. Times are in seconds. |
| opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. |
| resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. |
| created_at | ISO 8601 Timestamp representing the date and time the case was created at. |
| updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. |
| records | An array of records associated with the case, grouped by record type. Each record result includes the field id, name, and value. |
| records_meta | Metadata defining pagination params required to fetch additional records for the case. |
| priority | The case priority - critical, high, medium, low or info. |
| closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. |
| blocks | An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids. |
| tasks | An array of tasks associated with the case. |
### Sample response
```json
{
"cases": [
{
"case_id": 1,
"name": "Case 1..25",
"description": null,
"status": "OPEN",
"sub_status": {
"id": 1,
"name": "To do"
},
"priority": "LOW",
"url": "http:///team/276/cases/1",
"metadata": {
"foo": "bar"
},
"author": {
"user_id": "168",
"first_name": "Example",
"last_name": "Person",
"email": "person_2@example.com",
"avatar_url": "",
"is_service_account": false
},
"opened_by": null,
"resolved_by": null,
"assignees": [
{
"user_id": "176",
"first_name": "Example",
"last_name": "Person",
"email": "person_10@example.com",
"avatar_url": "",
"is_service_account": false
},
{
"user_id": "178",
"first_name": "Example",
"last_name": "Person",
"email": "person_12@example.com",
"avatar_url": "",
"is_service_account": false
},
{
"user_id": "180",
"first_name": "Example",
"last_name": "Person",
"email": "person_14@example.com",
"avatar_url": "",
"is_service_account": false
}
],
"tags": [
{
"id": 7,
"name": "Tag 1"
},
{
"id": 8,
"name": "Tag 2"
},
{
"id": 9,
"name": "Tag 3"
}
],
"sla": {
"remaining_time_seconds": 0,
"current_time_seconds": 0,
"percent_elapsed": 0,
"exceeded": false,
"sla_type": "completion"
},
"slas": [
{
"remaining_time_seconds": 0,
"current_time_seconds": 0,
"percent_elapsed": 0,
"exceeded": false,
"sla_type": "completion"
},
{
"remaining_time_seconds": 0,
"current_time_seconds": 0,
"percent_elapsed": 100,
"exceeded": true,
"sla_type": "response"
}
],
"activities": [
{
"id": 109,
"activity_type": "CREATED",
"value": "115",
"user": {
"user_id": "168",
"first_name": "Example",
"last_name": "Person",
"email": "person_2@example.com",
"avatar_url": "",
"is_service_account": false
},
"created_at": "2024-03-25T15:40:39Z"
},
{
"id": 111,
"activity_type": "COMMENTED",
"value": "I'm a comment",
"user": {
"user_id": "170",
"first_name": "Example",
"last_name": "Person",
"email": "person_4@example.com",
"avatar_url": "",
"is_service_account": false
},
"created_at": "2024-03-25T15:40:39Z"
},
{
"id": 113,
"activity_type": "COMMENTED",
"value": "I'm a comment",
"user": {
"user_id": "172",
"first_name": "Example",
"last_name": "Person",
"email": "person_6@example.com",
"avatar_url": "",
"is_service_account": false
},
"created_at": "2024-03-25T15:40:39Z"
}
],
"team": {
"id": 276,
"name": "Test team 1"
},
"linked_cases": [
{ "case_id": 2, "name": "Case 2" },
{ "case_id": 3, "name": "Case 3" }
],
"closure_conditions": [
{
"formula": "=SIZE(team_case.assignees) > 2",
"name": "Number of assignees"
}
],
"opened_at": "2024-03-25T15:40:39Z",
"resolved_at": null,
"created_at": "2024-03-25T15:40:39Z",
"updated_at": "2024-03-25T15:40:39Z",
"records": [
{
"record_type_id": 55,
"record_type_name": "Record type 2",
"record_type_record_results": [
{
"id": 59,
"results": [
{
"id": 59110,
"name": "Timestamp",
"value": "2024-04-16T08:02:03Z"
},
{
"id": 59109,
"name": "Story name",
"value": "Alert investigation"
}
],
"created_at": "2024-04-16T08:02:03Z"
},
{
"id": 58,
"results": [
{
"id": 58110,
"name": "Timestamp",
"value": "2024-04-16T08:02:03Z"
},
{
"id": 58109,
"name": "Story name",
"value": "Alert investigation #1"
}
],
"created_at": "2024-04-16T08:02:03Z"
}
]
},
{
"record_type_id": 54,
"record_type_name": "Record type 1",
"record_type_record_results": [
{
"id": 56,
"results": [
{
"id": 56108,
"name": "Timestamp",
"value": "2024-04-16T08:02:03Z"
},
{
"id": 56107,
"name": "Story name",
"value": "Alert investigation #2"
}
],
"created_at": "2024-04-16T08:02:03Z"
},
{
"id": 55,
"results": [
{
"id": 55108,
"name": "Timestamp",
"value": "2024-04-16T08:02:03Z"
},
{
"id": 55107,
"name": "Story name",
"value": "Alert investigation #3"
}
],
"created_at": "2024-04-16T08:02:03Z"
}
]
}
],
"actions": [
{
"id": 7,
"url": "http://example.com",
"label": "Hello, world!",
"action_type": "page"
}
],
"fields": [
{
"id": 1,
"value": "Tines",
"case_input": {
"id": 1,
"key": "company",
"name": "Company",
"validation_type": "none",
"validation_options": {}
}
}
],
"blocks": [
{
"id": 1,
"title": "Notes",
"slug": "blk_notes",
"block_type": "note",
"position": 1,
"hidden": false,
"block_group_id": null,
"elements": [
{ "element_id": 54, "id": 54 },
{ "element_id": 674, "id": 674 },
{ "element_id": 524, "id": 524 }
]
},
{
"id": 2,
"title": "Additional notes",
"slug": "blk_additional_notes",
"block_type": "note",
"position": 2,
"hidden": false,
"block_group_id": null,
"elements": [
{ "element_id": 235, "id": 235 },
{ "element_id": 342, "id": 342 },
{ "element_id": 744, "id": 744 }
]
}
],
"tasks": [
{
"id": 1,
"description": "Review security logs",
"completed": false,
"assignees": [
{
"id": "123"
},
{
"id": "456"
}
],
"created_at": "2024-03-25T15:40:39Z",
"updated_at": "2024-03-25T15:40:39Z"
},
{
"id": 2,
"description": "Contact affected users",
"completed": false,
"assignees": [],
"created_at": "2024-03-25T15:40:39Z",
"updated_at": "2024-03-25T15:40:39Z"
}
],
"activities_meta": {
"current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1",
"previous_page": null,
"next_page": null,
"next_page_number": null,
"per_page": 20,
"pages": 1,
"count": 3
},
"records_meta": {
"current_page": "https:///api/v2/cases/1/records?per_page=20&page=1",
"previous_page": null,
"next_page": null,
"next_page_number": null,
"per_page": 20,
"pages": 1,
"count": 4
},
"linked_cases_meta": {
"current_page": "https:///api/v2/cases/1/linked_cases?per_page=50&page=1",
"previous_page": null,
"next_page": null,
"next_page_number": null,
"per_page": 50,
"pages": 1,
"count": 2
}
}
],
"meta": {
"current_page": "https:///api/v2/cases?per_page=20&page=1",
"previous_page": null,
"next_page": null,
"next_page_number": null,
"per_page": 20,
"pages": 1,
"count": 1
}
}
```