## Overview
<p align="justify">
This endpoint let users retrieve a list of insights for a given AOI. It returns metadata about each insight, including progress, cost, timestamps, and creator information. Users can apply optional filters via query parameters to narrow down insights by ID, status, creator, or creation date. It is especially useful for reviewing all analytical outputs associated with an AOI. Authentication is required through a bearer token.

- Method: `GET`

- URL: `/v0/aoi/(aoiId)/insights`

- Operation: Retrieve a paginated list of all insights available to the authenticated user

- Authentication Required: Yes

</p>

## Authorization
<p align="justify">
You need the **api key** which you can get from the **API** tab in **Workspace Settings**. The api key is required in almost all the commands

```json
Authorization: <YOUR_API_KEY>
```
</p>

## Path parameters
<p align="justify">
Path parameters are part of the URL and used to specify which **AOI** you want to fetch insights for. In this endpoint, `{aoiId}` is a required path parameter that **uniquely identifies** the Area of Interest. Without it, the system wouldn’t know which AOI's insights to return.

| Name   | Type   | Required | Description                                   |
|--------|--------|----------|-----------------------------------------------|
| `aoiId`  | `string` | Yes      | Unique ID of the Area of Interest (AOI).      |

</p>

## Query Parameters 
<p align="justify">
Query parameters allow you to filter and refine the list of insights returned by the endpoint. For this endpoint, you can use parameters like `id`, `status`, `created_by`, and `created_on` to retrieve specific insights, limit results to certain users, or fetch insights created within a given timeframe.

| Name        | Type   | Required | Description                                                                 |
|-------------|--------|----------|-----------------------------------------------------------------------------|
| `id`          | `string` | No       | Fetch a specific insight using its unique ID.                              |
| `status`      | `string` | No       | Filter insights by their current status (e.g., running, completed).        |
| `created_by`  | `string` | No       | Filter insights based on the creator's user ID.                            |
| `created_on`  | `string` | No       | Filter by the creation timestamp (RFC3339 format, e.g., `2025-04-14T00:00:00Z`). |

</p>

## Response
<p align="justify">
A **200 OK** response indicates that the request to list insights was successful. The response contains an array of insight objects with details such as `name`, `status`, `creation time`, `creator ID`, `processing progress`, `cost`, and more. Each object represents a distinct insight generated for the specified AOI.

| Field                | Type      | Description                                               |
|----------------------|-----------|-----------------------------------------------------------|
| `name`                 | `string`    | Name of the insight                                       |
| `created_at`           | `string`   | Timestamp when the insight was created                    |
| `err_msg`              | `string`    | Error message if insight generation failed                |
| `created_by`           | `string`    | User ID of who created the insight                        |
| `estimated_time_in_min` | `integer`  | Estimated time required to generate the insight           |
| `deleted_at`           | `string`    | Deletion timestamp, if applicable                         |
| `id`                   | `string`    | Unique ID of the insight                                  |
| `status`               | `string`    | Status of the insight (e.g., pending, completed, failed)  |
| `input`                | `object[]`  | Array of input data objects. See [Data Types](/developer/insights/datatypes) for structure details. |
| `output`               | `object[]`  | Array of output data objects. See [Data Types](/developer/insights/datatypes) for structure details. |
| `metadata`             | `object`    | Additional metadata about the insight                     |
| `aoi_id`               | `string`    | ID of the AOI the insight belongs to                      |
| `cost`                 | `number`    | Cost associated with generating the insight               |
| `progress`             | `number`    | Progress percentage of insight generation                 |

Here is a sample response: 

```json 200
{
  "insights": [
    {
      "name": "<string>",
      "created_at": "<string>",
      "err_msg": "<string>",
      "created_by": "<string>",
      "estimated_time_in_min": 123,
      "deleted_at": "<string>",
      "id": "<string>",
      "status": "<string>",
      "input": [
        {
          "format": "raster",
          "name": "input_image",
          "type": "url",
          "stac_url": "<string>",
          "asset_source": {
            "id": "<string>",
            "type": "raw_mosaic"
          },
          "properties": {}
        },
        {
          "format": "date",
          "name": "start_date",
          "type": "string",
          "value": "<string>"
        }
      ],
      "output": [
        {
          "format": "raster",
          "name": "output_raster",
          "type": "url",
          "value": "<string>",
          "asset_source": {
            "id": "<string>",
            "type": "model_output"
          },
          "properties": {
            "bands": ["<string>"],
            "dtype": "<string>",
            "visualisation": {},
            "discretization": {}
          }
        },
        {
          "format": "vector",
          "name": "output_vector",
          "type": "url",
          "value": "<string>",
          "properties": {
            "geometry": "Polygon"
          }
        },
        {
          "format": "tabular",
          "name": "output_table",
          "type": "url",
          "value": "<string>",
          "properties": {
            "file_type": "csv",
            "file_schema": {
              "headers": ["<string>"]
            }
          }
        }
      ],
      "metadata": {},
      "aoi_id": "<string>",
      "cost": 123,
      "progress": 123
    }
  ]
}
```

A **400 error** occurs if the request is malformed or includes invalid query/path parameters. A **403 error** means access is **forbidden**, usually due to invalid credentials or insufficient permissions to view insights for the specified AOI. Both responses return structured error messages detailing the issue encountered.

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

## How to use the endpoint
<p align="justify">
1. **Construct your Request:**  
    Prepare the GET request with the required aoiId in the path and optional query parameters for filtering. Set the Authorization header with your valid bearer token.

2. **Send the Request:**  
    Send the request to: `https://api.pixxel.space/v0/aoi/{aoiId}/insights`

3. **Examine the Response:**  
    On success (200 OK), you'll receive a list of insights with full metadata. If there's an issue with the request, you’ll receive a structured error response (400 or 403) explaining the problem.
</p>