## Overview
<p align="justify">
This endpoint returns all visualizations associated with an AOI. You can apply filters based on User ID, Visualization ID, expression type, or specific index ID. Results are paginated using optional `offset` and `limit` query parameters. Each visualization object contains detailed metadata, including assets, index id, index name, expression type, created at, and user id. The API requires authentication through an API key and responds with structured data or error messages depending on request success.

- Method: `GET`

- URL: `/v0/aois/{aoi_id}/visualizations`

- Operation: Retrieve a list of visualizations avaiable for an AOI and their metadata

- Authentication Required: Yes

</p>

## Query Parameters
<p align="justify">

Query parameters are optional filters you can add to customize the response. They help you paginate results (`offset`, `limit`) or narrow them down using filters like `satellite_id`, `type`, `expression_type`, or `index_id`, making it easier to find specific indices efficiently.


| Parameter         | Type     | Required | Default | Description |
|------------------|----------|----------|---------|------------- |
| `offset`         | `integer`| No       | `0`     | Offset for pagination  |
| `limit`          | `integer`| No       | `10`    | Maximum number of results to return. |
| `type`           | `string` | No       | —       | Filter by index type (`custom` or `preset`). |
| `user_id`        | `string` | No       | —       | Filter visualzations by user ID who created. |
| `expression_type`| `string` | No       | —       | Filter by type of expression. |
| `index_id`       | `string` | No       | —       | Filter by a specific index ID. |
| `visualization_id`| `string`| No       | —       | Filter by a specific visualization ID. |

</p>

## Path Parameter
<p align="justify">
You need to enter the `aoi id` to get the list of visualizations generated using that AOI.

| Parameter    | Type     | Required | Description                     |
|--------------|----------|----------|---------------------------------|
| `aoi_id`     | `string` | Yes      | Unique ID of the AOI            |
</p>

## Response
<p align="justify">
The **List all visualizations** endpoint returns a `200 OK` response with a list of visualization objects and pagination details. Each visualization object includes metadata like assets, index id, index name, expression type, created at, and user id. If the request is malformed (e.g., invalid parameters), a `400 Bad Request` is returned. A `500 Internal Server Error` may occur due to unexpected server issues. All errors include a structured JSON response with a code, message, and optional details for debugging.

### Successful Response – 200 OK

Returns a list of visulaization objects with all related metadata and pagination information regarding the visualization

| Field             | Type       | Description                                                                  |
|-------------------|------------|------------------------------------------------------------------------------|
| `pagination`      | `object`          | Metadata about  |
| `total`           | `integer`         | Total number of indices available. |
| `offset`          | `integer`         | Current offset value. |
| `limit`           | `integer`         | Maximum number of indices returned per request. |
| `visualization`   | `array of string`           | List of visualization objects available in that AOI. |
| `aoi_id`          | `array of string`           | Unique ID of the AOI                         |
| `assets`          | `array of string`           | List of assets objects available in that visualization. |
| `created_at`      | `string`     | Timestamp when the visualization was created (ISO 8601 format)                   |
| `expression`      | `string`     | Mathematical expression applied using the selected bands                   |
| `expression_type` | `string`     | Type of the expression (e.g., "index", "formula")                          |
| `id`              | `string`     | Unique identifier of the visualization                                 |
| `index_id`        | `string`     | Unique ID of the AOI        |
| `index_name`      | `string`     | Human-readable name of the index                                  |
| `progress`        | `string`     | Details of progress in visualization creation                     |
| `rescale`         | `number`     | Min and max range used to normalize or rescale the output values           |
| `status`          | `string`     | Status of the visualization("creating", "success", "failed", "partial_success")    |
| `type`            | `string`     | Type of formula, usually "custom" for user-defined expressions             |
| `updated_at`      | `string`     | Timestamp when the visualization was last updated (ISO 8601 format)              |
| `user_id`         | `string`     | Unique ID of the user      |


Below is the complete JSON request for listing all indices using the **List indices** endpoint. Customize the values as needed for your search criteria:

```json 200
{
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 10
  },
  "visualization": [
    {
      "aoi_id": "<string>",
      "assets": [
        {
          "aoi_id": "<string>",
          "area_in_sq_m": 0,
          "asset_type": "<string>",
          "band_list": [
            "<string>",
            "<string>"
          ],
          "centroid": [
            77.55,
            12.95
          ],
          "created_at": "2022-11-14 12:55:49.125928+00:00",
          "date": "2022-11-14",
          "description": "<string>",
          "geometry": {
            "coordinates": [
              [
                [
                  123
                ]
              ]
            ],
            "type": "<string>"
          },
          "id": "<string>",
          "name": "<string>",
          "path": "https://storage.account",
          "progress": 0,
          "status": "success",
          "updated_at": "2022-11-14 12:55:49.125928+00:00",
          "visualization_id": "<string>"
        }
      ],
      "created_at": "2022-11-14 12:55:49.125928+00:00",
      "expression": "<string>",
      "expression_type": "index",
      "id": "<string>",
      "index_id": "<string>",
      "index_name": "<string>",
      "progress": 100,
      "rescale": [
        0,
        1
      ],
      "status": "success",
      "tenant_id": "<string>",
      "type": "custom",
      "updated_at": "2022-11-14 12:55:49.125928+00:00",
      "user_id": "<string>"
    }
  ]
}
```

### Error responses

Occurs when the request is malformed, such as missing or invalid parameters: (**400 - Bad Request and 500 - Internal Server Error**)

```json 400 500
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}
```
</p>

## How to use the endpoint
<p align="justify">
1. **Construct your Request:**  
    Add optional query parameters like `offset`, `limit`, `index_id`, `type`, or `expression_type` to filter or paginate results as needed. Include your API key in the headers for authorization and add mandatory path parameter.

2. **Send the Request:**  
    After constructing your request make the `GET` request to `https://api.pixxel.space/v0/aois/{aoi_id}/visualizations`. Include query parameters in the URL if needed (e.g., `?type=custom&limit=5`).

3. **Examine the Response:**  
    A successful `200 OK` response returns a JSON object with a list of available visualizations for an AOI and pagination metadata. Each visualization object includes metadata like assets, index id, index name, expression type, created at, and user id. In case of errors (like bad parameters or server issues), you'll receive a structured error message with details and status code.
</p>