## Overview
<p align="justify">
This endpoint allows users to either run a new insight on a selected Area of Interest (AOI) or get an estimate of the cost associated with that insight. By specifying processing blocks, input datasets, and metadata, users can configure customized geospatial analyses. **Dry Run**: Setting the `estimate` flag to `true` lets users preview the cost without executing the operation. This endpoint is crucial for initiating insights or assessing their resource requirements within the Pixxel platform.

- Method: `POST`

- Endpoint: `/v0/aoi/{aoi_id}/insights`

- Operation: Create a new insight or estimate its cost.

- 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">
The path parameter `aoi_id` is used to specify the Area of Interest on which the insight is to be created or costed. It is essential to target the right geospatial context for processing and ensures that insight operations are scoped to a valid AOI within the platform.

| Name    | Type   | Required | Description                        |
|---------|--------|----------|------------------------------------|
| `aoi_id`  | `string` | Yes      | ID of the AOI to run the insight on |
</p>

## Request Body
<p align="justify">
The request body defines the configuration for the insight. It includes the processing block, the required input asset IDs, optional metadata, and an optional flag for cost estimation. The flexibility allows either simulation of cost or actual insight generation depending on the use case.

| Name       | Type      | Required | Description                                                            |
|------------|-----------|----------|------------------------------------------------------------------------|
| `project_id` | `string`    | No       | ID of the project under which the insight will be created                   |
| `name`       | `string`    | No       | Human-readable name for the insight                                    |
| `block`      | `object`    | Yes      | Describes the processing block to use for generating the insight       |
| `input`      | `[]object`  | Yes      | Array of input objects. See [Data Types](/developer/insights/datatypes) for details on structure and how to populate values. |
| `metadata`   | `object`    | No       | Additional metadata as key-value pairs                                 |
| `estimate`   | `boolean`   | No       | If `true`, returns cost estimate instead of creating an insight        |

Here is a sample body: 

```json body
{
  "project_id": "<string>",
  "name": "<string>",
  "block": {
    "name": "<string>",
    "string": "<string>",
    "version": "<string>"
  },
  "input": [
    {
      "name": "<string>",
      "format": "<string>",
      "value": "<string>",
      "type": "<string>",
      "properties": {}
    }
  ],
  "metadata": {},
  "estimate": true
}
```
</p>


## Response
<p align="justify">
A **200 OK** response is returned when the `estimate` flag is `true`, indicating the computed cost of executing the insight. A **201 Created** response indicates successful creation of the insight with a confirmation message and the insight ID. Both responses confirm the request was processed without errors.

```json 200
{
  "estimate": 123
}
```

- Returned when the estimate flag is set to true. Provides the cost of executing the insight.

```json 201
{
  "id": "<string>",
  "message": "<string>"
}
```

- Returned when the insight is created with the estimate flag set to false.

A 400 Bad Request response is returned when required parameters are missing or malformed. A 403 Forbidden error is returned if the user lacks access to the specified AOI or project. Both responses return a structured error message with code, message, and optional details for troubleshooting.

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

## How to use the Endpoint
<p align="justify">
1. **Get the Block's Input Schema:**
    Use the [List Blocks API](/api-reference/blocks/list-blocks-insights) to get the input structure for your chosen block. See [Data Types](/developer/insights/datatypes) for details on how to populate the input values.

2. **Construct your Request:**
    Copy the input structure from the block spec and add `value` or `stac_url` for each input. Set estimate to true to fetch cost or false to run the insight. Set the Authorization header with your token and replace aoi_id in the URL.

3. **Send the Request:**
    Make a POST request to `https://api.pixxel.space/v0/aoi/{aoi_id}/insights`. Include your request body and authorization header.

4. **Examine the Response:**
    If estimate is true, you'll receive the cost estimate. If false, the response will confirm insight creation with an ID and message. Handle errors by checking status codes and structured error responses.
</p>