​
Overview

This endpoint lets 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

​
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

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.

NameTypeRequiredDescription
aoiIdstringYesUnique ID of the Area of Interest (AOI).

​
Query Parameters

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.

NameTypeRequiredDescription
idstringNoFetch a specific insight using its unique ID.
statusstringNoFilter insights by their current status (e.g., running, completed).
created_bystringNoFilter insights based on the creator’s user ID.
created_onstringNoFilter by the creation timestamp (RFC3339 format, e.g., 2025-04-14T00:00:00Z).

​
Response

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.

FieldTypeDescription
namestringName of the insight
created_atstringTimestamp when the insight was created
err_msgstringError message if insight generation failed
created_bystringUser ID of who created the insight
estimated_time_in_minintegerEstimated time required to generate the insight
deleted_atstringDeletion timestamp, if applicable
idstringUnique ID of the insight
statusstringStatus of the insight (e.g., pending, completed, failed)
inputnumber[]Input data IDs used to generate the insight
outputnumber[]Output data IDs resulting from the insight
metadataobjectAdditional metadata about the insight
aoi_idstringID of the AOI the insight belongs to
costnumberCost associated with generating the insight
progressnumberProgress percentage of insight generation
Here is a sample response:
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": [
        123
      ],
      "output": [
        123
      ],
      "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.
400 403
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  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.