get_test_cases

Retrieves test cases configured for an AI Agent. Supports listing all test cases, filtering by name, retrieving full details for a single test case, and sorting by last run.

Example prompts

“Show me all test cases on our Agent.”
“Find test cases whose name mentions ‘refund’.”
“Which test cases have not run recently?”

Parameters

Parameter	Type	Description
`test_case_id`	string	Optional. Return full details for a single test case.
`name_filter`	string	Optional. Case-insensitive substring match against test case names. Ignored when `test_case_id` is provided.
`group_by_last_run`	boolean	Optional. Set to `true` to sort the test cases by their last run, newest first, and add `last_run_at` to each case. Cases that never ran come last. Default `false`.
`cursor`	string	Optional. Opaque cursor returned as `next_cursor` by the previous call. Omit it to fetch the first page. Pass the same other parameters as the call that returned it.
`limit`	integer	Optional. Maximum number of test cases in one page, from 1 to 100. Pages are also limited by size, so a page can hold fewer.

Pagination

A list of test cases is paged by size. If the response has a non-null next_cursor, pass it back as cursor to fetch the next page. Repeat until next_cursor is null before you answer a question about the whole set.

If a test case is created or deleted between calls, the tool rejects the cursor. When group_by_last_run is true, a run that finishes between calls also rejects it. Call again without cursor to start from the first page.

A test case too large for one page arrives with its longest text cut and a truncated_fields list that names the cut fields. To read the full definition, request the case by test_case_id. Do not reuse a case that has truncated_fields.

Response

When listing, each page returns test_cases, total_count, and next_cursor. Each test case includes:

ID and name.
Channel ID and language.
User message or scenario.
Success criteria.
Variables.
Created and last-updated timestamps, with the users who made them.
last_run_at, when group_by_last_run is true. The value is null for a case that never ran.

When requesting a single test case by ID, the full test case definition is returned in one response, without paging.