# Lists Cuppings

Retrieves a list of cuppings, their cupped coffees and their result summary.

Endpoint: POST /quality.cupping.listCuppings
Security: oauth2

## Request fields (application/json):

  - `params` (object)

  - `params.filter` (object)
    Defines all required and optional filter parameters for the operation.

  - `params.filter.startDate` (object)

  - `params.filter.startDate.from` (string)
    Filters the results to include only records created on or after this date. The date must be provided in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). The filter is inclusive.
    Example: "2023-10-05T14:48:00Z"

  - `params.filter.startDate.to` (string)
    Filters the results to include only records created before this date. The date must be provided in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). The filter is exclusive.
    Example: "2023-10-05T14:48:00Z"

  - `params.filter.state` (string)
    The state of a cupping.
    Enum: "OPEN", "CLOSED", "DRAFT"

  - `params.pagination` (object)
    Defines all required and optional pagination parameters for the operation.

  - `params.pagination.limit` (integer)
    The number of elements to be returned
    Example: 20

  - `params.pagination.after` (string)
    The cursor to retrieve the next page. This is an opaque value that should not be interpreted by the client.
    Example: "aBc="

## Response 200 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful.
    Example: true

  - `result` (object)
    Contains the response data of a successful request.

  - `result.cuppings` (array)

  - `result.cuppings.id` (string)
    The unique identifier of the cupping.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `result.cuppings.cuppingNumber` (string)
    A human-readable identifier for the cupping.
    Example: "CUP-2023-001"

  - `result.cuppings.startDate` (string)
    The start date of the cupping in ISO 8601 format.
    Example: "2023-10-05T14:48:00Z"

  - `result.cuppings.state` (string)
    The state of a cupping.
    Enum: "OPEN", "CLOSED", "DRAFT"

  - `result.cuppings.cuppingSheet` (object)
    The cupping sheet used for this cupping.

  - `result.cuppings.cuppingSheet.name` (string)

  - `result.cuppings.cuppedCoffees` (array)
    The coffee that was cupped in this session.

  - `result.cuppings.cuppedCoffees.id` (string)
    The cupped coffee's unique identifier.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `result.cuppings.cuppedCoffees.cuppedCoffeeNumber` (string)
    A human-readable identifier for the cupped coffee.
    Example: "QC-0001"

  - `result.cuppings.cuppedCoffees.averageScore` (number)
    The average score of the cupped coffee.
    Example: 85.5

  - `result.cuppings.cuppedCoffees.cuppedLot` (object)
    A reference to a polymorphic object, containing its unique identifier and type.

  - `result.cuppings.cuppedCoffees.cuppedLot.id` (string)
    The unique identifier of the referenced entity.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `result.cuppings.cuppedCoffees.cuppedLot.type` (string)
    The type of the referenced entity, which can be used to determine at which endpoint the 'id' field can be used to retrieve the full entity details.
    Example: "INVENTORY_ROAST"

  - `meta` (object)
    Contains the metadata (e.g. pagination information) of the response.

  - `meta.pagination` (object)
    Represents the pagination fields of the response.

  - `meta.pagination.endCursor` (string)
    Cursor value to retrieve the records of the next page. If there no further pages, this value is null.
    Example: "aBc="

## Response 400 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful or not

  - `error` (object)

  - `error.code` (string)
    Specifies error code that can be handled programmatically.
    Example: "invalid_parameter"

  - `error.message` (string)
    A detailed description of the occurred error.
    Example: "Invalid parameter provided"

## Response 401 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful or not

  - `error` (object)

  - `error.code` (string)
    Specifies error code that can be handled programmatically.
    Example: "invalid_parameter"

  - `error.message` (string)
    A detailed description of the occurred error.
    Example: "Invalid parameter provided"

## Response 403 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful or not

  - `error` (object)

  - `error.code` (string)
    Specifies error code that can be handled programmatically.
    Example: "invalid_parameter"

  - `error.message` (string)
    A detailed description of the occurred error.
    Example: "Invalid parameter provided"

## Response 422 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful or not

  - `error` (object)

  - `error.code` (string)
    Specifies error code that can be handled programmatically.
    Example: "invalid_parameter"

  - `error.message` (string)
    A detailed description of the occurred error.
    Example: "Invalid parameter provided"

## Response 500 fields (application/json):

  - `ok` (boolean)
    Indicates whether the request was successful or not

  - `error` (object)

  - `error.code` (string)
    Specifies error code that can be handled programmatically.
    Example: "invalid_parameter"

  - `error.message` (string)
    A detailed description of the occurred error.
    Example: "Invalid parameter provided"