This article describes how to work with lenses in the Pattern API. Typically, the primary objective in working with lenses is to retrieve a list of cases.

Listing Lenses

Lenses are the primary grouping for cases within Pattern. To see a list of lenses within your account, use the endpoint "pattern/lens/list". A sample cURL request might look like the following:

curl --location --request POST 'https://service.patterndata.io/pattern/lens/list' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Token>'

The resulting json will return a list of lens objects, which have an "id" and "name". 

Listing All Cases

To retrieve all lenses within a case, use the "pattern/case/list" endpoint. This endpoint requires a "lensId". Valid lens ids can be looked up using the Listing Lenses functionality. For lenses with a large volume, paginating through a defined result set is recommended. A sample cURL request might look like the following:

curl --location 'https://service.patterndata.io/pattern/case/list' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Token>' \
--data '{
  "lensId": "paraquat",
  "offset": 0,
  "limit": 10000,
  "filters": {}
}'

This will retrieve the first 10000 cases within the lens id "paraquat" with no filters. If the Paraquat lens has more than 10000 cases, repeat the call resetting the offset value by the limit until the total case count is reached. 

Listing Cases with Filters

The examples below are intended to highlight some common use cases in filtering cases. For the full list of filter parameters, see the Open Api Specification within the Setup article here.

Listing Cases Changed in a Window

It is frequently helpful to retrieve cases which have been changed or updated within a timeframe. To filter on cases which have had any changes in a time frame, use the "modifiedAtMin" and "modifiedAtMax" filter settings within the list cases endpoint. 

curl --location 'https://service.patterndata.io/pattern/case/list' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Token>' \
--data '{
"lensId": "paraquat",
  "offset": 0,
  "limit": 10000,
  "filters": {
    "modifiedAtMin": "2023-01-01",
    "modifiedAtMax": "2023-12-31"
  }
}'

This request will return only cases that have been changed in the calendar year 2023. 

Note that the min and max dates in the filter are inclusive.

Listing Cases Reviewed in a Window

The prior section will return any case with any changes over the specified time period. Often, that will show cases with in-progress reviews. To retrieve only cases which were marked as "Review Complete" within a timeframe, use the "reviewStatusUpdatedAtMin" and "reviewStatusUpdatedAtMax" filter settings within the list cases endpoint. 

curl --location 'https://service.patterndata.io/pattern/case/list' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Token>' \
--data '{
"lensId": "paraquat",
  "offset": 0,
  "limit": 10000,
  "filters": {
    "reviewStatusUpdatedAtMin": "2023-01-01",
    "reviewStatusUpdatedAtMax": "2023-01-31"
  }
}'

This request will return only cases that were reviewed within the month of January 2023. 

Note that the min and max dates in the filter are inclusive.

Listing Cases that within a Review Status

To retrieve only review complete cases, you can use the "reviewStatus" filter setting.

curl --location 'https://service.patterndata.io/pattern/case/list' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Token>' \
--data '{
  "lensId": "paraquat",
  "offset": 0,
  "limit": 10000,
  "filters": {
    "reviewStatus": "complete"
  }
}'

This request will return only cases which are currently "Review Complete".