Retrieve Cases

Overview

The API allows you to manage and search cases.
This article provides details about the available endpoints, request parameters, pagination, and example responses.

Prerequisites: Obtaining API Key

Endpoint

[POST] api.wiv.ai/v2/cases/search

Search cases. Supports filtering and pagination.

Authentication

• Requires valid API Key authentication credentials.

Request Body Parameters (JSON)

Request Examples

1. Search all cases

   POST /v2/cases/search Content-Type: application/json 
   {}
   

2. Specific max_returned_items

   POST /v2/cases/search
   Content-Type: application/json 
   {
       "max_returned_items": 50
   }

3. With filters and date range 

   {
       "date_range": {
           "start": "2024-01-01",
           "end": "2024-12-31"
       }
   }

   
   

Pagination

Large case search results are returned in pages.
The API uses a scroll-based pagination mechanism to deliver results consistently.

How it Works

1. Initial Request

   • Send your search request with max_returned_items (default: 250).

   • The response will include data (cases) and a next_page_key object if more results exist.

2. Fetching Next Page

   • Copy the scroll_id from the response next_page_key.

   • Provide it in your next request under start_page_key.scroll_id.

3. End of Results

   • When there are no further results, "next_page_key": null is returned.

Request Example (Next Page)

POST /v2/cases/search Content-Type: application/json 
{
    "max_returned_items": 25,
    "start_page_key": {
        "scroll_id": "FGluY2x1ZGVfY29u==..."
    }
}

Response Example (With Next Page Key)

{
    "data": [
        {
            "case_id": "case_12345",
            ....
            "case_type": "EC2 Stopped Instances"
        }
    ],
    "next_page_key": {
        "scroll_id": "FGluY2x1Z==..."
    }
}

Key Notes

• Opaque scroll ID: The scroll_id is an encoded system token. Always use it as returned, without modification.

• Consistency: The scroll ensures results are returned in a stable order during the pagination session.

• Session scope: New cases created during an active scroll session may not appear until you start a new search.

• Performance:

  • Use page sizes of 25–100 items for UI-based pagination.

  • Use larger page sizes (up to 500) for backend batch processing.

Error Responses

• Apply specific date ranges in /cases/search for faster responses.

• Always use pagination for large result sets.

• Cache frequently accessed queries where possible.

Rate Limits

Standard API rate limits apply. Contact your administrator for details.