> ## Documentation Index
> Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Structure

> Understand the unified request and response format used across all Falcon API endpoints.

Falcon uses a unified JSON query system — every dataset uses the same POST request format and response schema. Once you understand this structure, you can query any Falcon endpoint without relearning the request format.

All Falcon queries are sent to:

```
POST https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized
```

## Request structure

Send a JSON body with each request. The `agent_id` determines which dataset is returned. All other fields are optional.

```json theme={null}
{
  "agent_id": 574,              // Required — selects the endpoint
  "params": {                   // Optional — filter parameters
    "min_volume": "1000",
    "closed": "False"
  },
  "pagination": {               // Optional — control result size
    "limit": 10,                // 1–200, default varies by endpoint
    "offset": 0                 // Skip N results for pagination
  },
  "formatter_config": {         // Optional — response formatting
    "format_type": "raw"        // "raw" returns structured JSON
  }
}
```

### Request fields

| Field | Type | Required / default | Description |
| - | - | - | - |
| `agent_id` | number | Required | Identifies the dataset being queried. Each Falcon dataset maps to a specific `agent_id`. See [Core Concepts](/docs/reference/core-concepts) for the full list. |
| `params` | object | Optional | Dataset-specific filter parameters. Common filters include market status, market slug, timestamps, and trader addresses. The available filters depend on the dataset you are querying. |
| `pagination.limit` | number | Optional; default `10` | Maximum number of records returned per request. Accepted range: `1–200`. |
| `pagination.offset` | number | Optional; default `0` | Number of records to skip before returning results. Use this to paginate through large datasets. |
| `formatter_config.format_type` | string | Optional | Output format for the response data. Currently supported value: `"raw"`. |

## Tips

> [!TIP]
>
> All `params` values must be strings, even numbers (e.g. `"900"` not `900`).

> [!TIP]
>
> Omit optional fields entirely rather than passing null — the API ignores unknown fields.

> [!TIP]
>
> Use `limit:200` for bulk retrieval and check `has_more` in the response for pagination.

***

## Response structure

All Falcon API endpoints use a single POST URL with a JSON body. The `agent_id` determines which data source to query.

```json theme={null}
{
  "timestamp": "2026-04-06T12:00:00Z",     // Server timestamp
  "params": {                                // Echo of your request params
    "min_volume": "1000",
    "closed": "False"
  },
  "pagination": {
    "limit": 10,                             // Your requested limit
    "offset": 0,                             // Your requested offset
    "has_more": true                         // More results available?
  },
  "data": {
    "results": [                             // Array of result objects
      { ... },
      { ... }
    ]
  },
  "request_id": "abc-123-def"               // Unique request identifier
}
```

| Field | Type | Description |
| - | - | - |
| `timestamp` | string | Server timestamp indicating when the response was generated. Formatted as an ISO 8601 string (e.g., `"2025-01-09T19:12:50Z"`). |
| `params` | object | Echo of the query parameters used in your request. Use this to verify that your filters were applied correctly. |
| `pagination.limit` | number | Number of records returned in this response. |
| `pagination.offset` | number | Starting index of the returned records within the full dataset. |
| `pagination.has_more` | boolean | Whether additional records are available beyond the current page. When `true`, increment `offset` by `limit` and send another request. |
| `data.results` | array | The returned dataset records. The structure of each object depends on the specific dataset being queried. |
| `request_id` | string | Unique identifier for debugging. Include in support requests. |

## Pagination

To paginate through results, check `has_more` in the response and increment `offset` by limit:

```
// Page 1
{ "pagination": { "limit": 50, "offset": 0 } }

// Page 2 (if has_more: true)
{ "pagination": { "limit": 50, "offset": 50 } }

// Page 3
{ "pagination": { "limit": 50, "offset": 100 } }
```

# Timestamp Format

All timestamps in responses use ISO 8601 format in UTC: `2026-04-06T12:00:00Z`. Some endpoints accept Unix timestamps as strings in params — check each endpoint's documentation for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.