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.

{
  "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 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

All params values must be strings, even numbers (e.g. "900" not 900).

Omit optional fields entirely rather than passing null — the API ignores unknown fields.

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.

{
  "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.

Reference

API Structure

Request structure

Request fields

Tips

Response structure

Timestamp Format

​Request structure

​Request fields

​Tips

​Response structure

​Pagination

​Timestamp Format

Request structure

Request fields

Tips

Response structure

Pagination

Timestamp Format