# Retrieve a list of cases

Retrieve a list of cases.

Endpoint: GET /cases
Version: 2.68.0
Security: OAuth2

## Query parameters:

  - `projectIds` (array)
    Used to retrieve cases belonging to specific projects only. Multiple project identifiers can be provided. By default, cases from all accessible projects are returned.

  - `offset` (integer)
    A zero-based offset of the first item in the data collection to return.

  - `limit` (integer)
    Limit the amount of items returned in the response. If the value exceeds the maximum, then the maximum value will be used.

  - `sort` (string)
    The field to sort reponse items by.
    Enum: "createdAt", "-createdAt", "+createdAt", "updatedAt", "-updatedAt", "+updatedAt"

  - `state` (array)
    Used to retrieve cases that are in specific states only. Multiple states can be used for this filtering. By default, cases in all states are returned.
    Enum: "done", "doneAutomatically", "failed", "inCompletion", "new", "processing", "rejected", "reviewRequired", "transferFailed", "transferred"

  - `fileBatchId` (string)
    File batch identifier to retrieve cases that were created from that file batch.

## Response 200 fields (application/json):

  - `data` (array, required)

  - `data.id` (string, required)
    Example: "69c5a545-7b2f-4f4a-833b-45feff1056c7"

  - `data.createdAt` (string, required)
    Example: "2020-01-01T15:00:00Z"

  - `data.createdBy` (string, required)

  - `data.completedAt` (string)
    Example: "2020-01-01T15:00:00Z"

  - `data.completedBy` (string)

  - `data.updatedAt` (string)
    Example: "2020-01-01T15:00:00Z"

  - `data.updatedBy` (string)

  - `data.transferSuccessful` (boolean)
    Indicates whether the case was transferred successfully to the target system. Will be null if the transfer status is not yet known (e.g. because the case is still being processed or the transfer information has not been provided yet).
    Example: true

  - `data.transferMessage` (string)
    May contain additional information about the transfer, especially in the case of a failed transfer.
    Example: "Upload failed due to ERP being down"

  - `data.files` (array, required)
    List of files that are part of the case, each with their assigned role and main document flag.

  - `data.files.id` (string, required)
    Identifier of the file as returned by the upload endpoint.
    Example: "197c997c-4bab-41e7-b33d-bad287046914"

  - `data.files.type` (string, required)
    The role the file plays in the case (e.g. mainDocument, attachment). Must only contain letters from the Latin alphabet with no whitespace or special characters.
    Example: "salesOrder"

  - `data.files.mainFile` (boolean, required)
    Indicates whether this file is the main document of the case.
    Example: true

  - `data.entities` (object)
    Entities extracted from the case by the AI Agents.
    Example: {"currency":"EUR","items":[{"name":"High quality cement for rabbit hole sealing","qty":1}],"number":"2018-DE-0011122351","qty":2}

  - `data.externalId` (string)
    Example: "case-0001"

  - `data.externalData` (object)
    Example: {"internalSystemId":"sap-01"}

  - `data.projectId` (string, required)
    Example: "69bbd22c92f3c3ee4a097784"

  - `data.fileBatchId` (string)
    Identifier of the file batch this case was created from. Only present for cases created via POST /cases/process-file-batch.
    Example: "a1b0020b-8ef9-4801-aeef-979224af0bab"

  - `data.previewFileId` (string)
    Identifier of the file used as the case preview, if any.
    Example: "197c997c-4bab-41e7-b33d-bad287046914"

  - `data.state` (string, required)
    Enum: "done", "doneAutomatically", "failed", "inCompletion", "new", "processing", "rejected", "reviewRequired", "transferFailed", "transferred"

  - `data.url` (string)
    URL to access the case.
    Example: "https://example.com/cases/6040dc9680b782b365ea77d5"

  - `limit` (integer)
    The limit used for this page of results. This will be the same as the limit query parameter unless it exceeds the maximum allowed value.
    Example: 20

  - `offset` (integer)
    The offset used for this page of results. This will be the same as the offset query parameter.

  - `totalCount` (integer)
    The total number of elements in the data attribute.
    Example: 1000

## Response 400 fields (application/json):

  - `detail` (string, required)
    A human readable explanation of the error.

  - `status` (integer, required)
    The HTTP status code.

  - `title` (string, required)
    A short summary of the error


## Response 429 fields