Skip to main content

​
Overview

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

​
Authorization

You need the api key which you can get from the API tab in Organization Settings. The api key is required in almost all the commands

Authorization: <YOUR_API_KEY>

​
Path Parameters

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.

NameTypeRequiredDescription
aoi_idstringYesID of the AOI to run the insight on

​
Request Body

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.

NameTypeRequiredDescription
project_idstringNoID of the project under which the insight will be created
namestringNoHuman-readable name for the insight
blockobjectYesDescribes the processing block to use for generating the insight
input[]objectYesArray of input objects. See Data Types for details on structure and how to populate values.
metadataobjectNoAdditional metadata as key-value pairs
estimatebooleanNoIf true, returns cost estimate instead of creating an insight
Here is a sample body:
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
}

​
Response

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.

200
{
  "estimate": 123
}
  • Returned when the estimate flag is set to true. Provides the cost of executing the insight.
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.
400 403
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the Endpoint

  1. Get the Block’s Input Schema: Use the List Blocks API to get the input structure for your chosen block. See Data Types 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.