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

# Report response formats

> Interpret discovery, parameter forms, report tables, typed cells, objects, and completion states.

There are two response levels: raw HTTP responses from the Agent API and the objects assembled by its JavaScript helpers.
Field names are case-sensitive. The examples below illustrate structure; report IDs, parameters, columns, and values depend on your report.

## HTTP query envelopes

Information Query returns an envelope:

```json theme={null}
{
  "ok": true,
  "Stanza": {
    "nodeInfos": {
      "nodeInfo": {
        "id": "Client Reports\\Monthly usage.rpx",
        "parentId": "Client Reports",
        "hasCommands": "true",
        "hasChildren": "false"
      }
    }
  }
}
```

This discovery example omits XML metadata and other node attributes.
Always inspect `ok`, even after HTTP success. Failed queries can include `errorText`, `errorType`, `errorCode`, and `ErrorElement`.

XML is represented as JSON using these conventions:

| Representation                   | Meaning                                                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `__name`, `__ns`                 | XML element name and namespace.                                                                                |
| Named properties such as `field` | Child elements. One child is an object; repeated children are an array. A missing child can be absent.         |
| `value`                          | Text content. A `<value>` child can itself have a `value` text property.                                       |
| Attribute properties             | Usually strings, including values such as `"true"`, `"false"`, and sequence numbers.                           |
| `__ordered`                      | Ordered child elements when different child names occur together. Use this to preserve mixed table-cell order. |

Normalize absent, single, and repeated elements before iteration:

```javascript theme={null}
const asArray = value => value == null ? [] : Array.isArray(value) ? value : [value];
```

The `GetReports` helper reduces the matching report nodes to a string array.
The raw HTTP envelope is not itself that array.

## Parameter forms

Parameter retrieval returns an XMPP data form in `Stanza.x`. The JavaScript helper returns that form directly.

Illustrative form, with XML metadata omitted:

```json theme={null}
{
  "type": "form",
  "title": { "value": "Monthly usage" },
  "field": [
    {
      "var": "Month",
      "type": "text-single",
      "label": "Month",
      "desc": { "value": "Month to include, in YYYY-MM format." },
      "required": {},
      "value": { "value": "2026-08" }
    },
    {
      "var": "Format",
      "type": "list-single",
      "label": "Format",
      "value": { "value": "summary" },
      "option": [
        { "label": "Summary", "value": { "value": "summary" } },
        { "label": "Details", "value": { "value": "details" } }
      ]
    }
  ]
}
```

| Field property  | How to use it                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `var`           | Exact submission key. Do not replace it with the displayed label.                                     |
| `type`          | Input type, such as `text-single`, `boolean`, `list-single`, `list-multi`, `hidden`, or `fixed`.      |
| `label`, `desc` | Text for the person supplying parameters.                                                             |
| `required`      | Presence of this element marks a required field. It need not be a JSON boolean.                       |
| `value`         | Default or supplied value, normally nested as `{ "value": "text" }`. Repeated values can be an array. |
| `option`        | Allowed options; submit their values rather than their display labels.                                |

Honor any validation information in the form. Do not assume every report accepts dates, the same date format, or the same field names.
Preserve hidden fields. Fixed fields describe the form rather than requesting user input.
An actual empty form can be submitted with no fields; a missing form should be investigated.

## Assembled JavaScript results

`ExecuteReport` returns a completed query record assembled from progress events.
This illustrative result contains one section and one table. A report can contain multiple tables, nested sections, and generated objects.

```json theme={null}
{
  "Sections": [
    {
      "Type": "Section",
      "Header": "Usage",
      "Items": [
        {
          "Type": "Table",
          "Id": "usage",
          "Name": "Monthly usage",
          "Columns": [
            { "Id": "month", "Header": "Month" },
            { "Id": "total", "Header": "Total", "NrDecimals": "2" }
          ],
          "Records": [
            ["2026-08", { "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }]
          ],
          "Done": true
        }
      ]
    }
  ],
  "Objects": [],
  "Tables": {
    "usage": {
      "Type": "Table",
      "Id": "usage",
      "Name": "Monthly usage",
      "Columns": [
        { "Id": "month", "Header": "Month" },
        { "Id": "total", "Header": "Total", "NrDecimals": "2" }
      ],
      "Records": [
        ["2026-08", { "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }]
      ],
      "Done": true
    }
  },
  "Ok": true,
  "Errors": [],
  "HasErrors": false,
  "Started": true,
  "Done": true,
  "Title": "Monthly usage"
}
```

| Property              | Meaning                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `Tables`              | Object keyed by table ID, not an array. Iterate with `Object.values(result.Tables)`.              |
| `Sections`            | Hierarchical presentation. Sections have `Type: "Section"`, `Header`, and `Items`.                |
| `Objects`             | Generated objects with `Type: "Object"`, `ContentType`, and `Base64`.                             |
| `Title`               | Report title, if supplied.                                                                        |
| `Started`, `Done`     | Execution lifecycle flags. `Done` alone does not distinguish successful completion from an abort. |
| `HasErrors`, `Errors` | Errors recorded by the helper. An abort adds `"Aborted."`.                                        |
| `Ok`                  | Initialized to true by the current helper. Do not use it alone to determine success.              |

Section `Items` can contain nested sections, tables, objects, and messages.
A table can appear in a section and in `Tables`; these are two ways to access the same output, not two separate tables.
Messages have `Type: "Message"`, `Level`, and `Text`. Inspect their levels and text; they are not all copied into `Errors`.

The helper removes `Status` when the query ends. Do not require it in a completed result.
An HTTP execution acknowledgment never contains this assembled object.

## Read tables and cells

`Columns` defines display order. Each entry in `Records` is a row array in that same order:
`Records[rowIndex][columnIndex]` belongs to `Columns[columnIndex]`.

Columns contain `Id` and may include `Header`, `SourceId`, `Partition`, `ForegroundColor`, `BackgroundColor`, `Alignment`, and `NrDecimals`.
Do not assume a particular table ID, column count, or column name unless your provider defines that contract for your report.

| Cell shape                                                                     | Meaning                                                                           |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| String or other scalar                                                         | Text or a scalar value. Numeric, date, and boolean XML values can remain strings. |
| `{ "Type": "Quantity", "Magnitude": "125.5", "Unit": "kWh" }`                  | Value with a unit.                                                                |
| `{ "Type": "Measurement", "Magnitude": "20.1", "Unit": "°C", "Error": "0.2" }` | Value, unit, and measurement error.                                               |
| `{ "Type": "EncodedObject", "ContentType": "image/png", "Base64": "..." }`     | Encoded content within a table cell.                                              |
| Missing or null value                                                          | Empty cell. Preserve its position instead of shifting later cells.                |

For raw `newRecords` progress, cells retain their XML names, such as `string`, `double`, `quantity`, or `measurement`.
Read `record.__ordered` when present; grouping by cell type would scramble column order.
For quantities and measurements, the raw attributes are `m` (magnitude), `u` (unit), and `e` (measurement error).

Convert values according to the report's contract. Avoid converting large integers to JavaScript numbers if precision matters.
Render labels and text as text. Decode objects according to an allowed content type rather than inserting arbitrary output as HTML.

## Handle partial or failed results

* Reject HTTP failures and Information Query responses with `ok: false` before consuming success data.
* Wait for query completion, not just the first table or its `Done` flag.
* Treat aborted queries, missing progress, and client deadlines as incomplete results.
* Inspect helper `HasErrors`, `Errors`, and section messages before displaying a result as successful.

See [Reports troubleshooting](/reports/troubleshooting) for the next check for each symptom.