> ## 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.

# Reports API

> Discover, run, and display the reports shared with your Agent API account.

Use the Reports API to list reports available to your account, supply their parameters, and retrieve tables, messages, and generated objects.
Your application connects to the Neuron over HTTPS using the Agent API credentials supplied to you.

For dashboards, run reports on a backend schedule or through a controlled manual refresh.
Serve cached results to viewers; do not execute an expensive report on every page load.
Follow [Refresh reports for a dashboard](/reports/dashboard-integration) for scheduling, concurrency, and stale-data handling.

## Get your connection details

Your provider supplies these values:

| Value       | Example                            | Purpose                                                                                   |
| ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------- |
| Neuron host | `neuron.example.com`               | Host serving the Agent API. Use `https://neuron.example.com/Agent/...` for HTTP requests. |
| Username    | `client.reports`                   | Account used to sign in. Preserve the supplied spelling.                                  |
| Password    | Supplied separately                | Used to sign the login request and obtain a session token.                                |
| Reports JID | `reports@neuron.example.com`       | Address of the Neuron that hosts the reports.                                             |
| Report ID   | `Client Reports\Monthly usage.rpx` | Exact identifier returned by report discovery.                                            |
| Language    | `en`                               | Language requested for labels and report text.                                            |

**Reports JID is the report server's address.** It is separate from your login username and the report's filename.
Do not construct it from the HTTP host: the report server may use another XMPP domain.
Use the exact address supplied by your provider.

The provider configures report permissions and approves the required presence subscription.
You do not need a Neuron administrator login or a digital identity to use this report authorization flow.

## Endpoints used by reports

The main report endpoint is **`POST https://<NEURON_HOST>/Agent/Xmpp/InformationQuery`**.
Use it to discover reports, fetch a parameter form, and start execution. The XML command in its JSON body selects the action.

All requests below go to the Agent API host supplied with your account. The Reports JID is the target inside the request body.

| Step                         | HTTP endpoint                       | Request and result                                                                                     |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Sign in                      | `POST /Agent/Account/Login`         | Send username, nonce, HMAC signature, and session duration; retain `jwt` and `expires`.                |
| Resolve a bare Reports JID   | `POST /Agent/Xmpp/PresenceProbe`    | Send `to`; retain the returned full `jid`.                                                             |
| List reports                 | `POST /Agent/Xmpp/InformationQuery` | Send `type: "get"` with `getAllNodes` and `src='Reports'`; read `Stanza.nodeInfos.nodeInfo`.           |
| Fetch parameters             | `POST /Agent/Xmpp/InformationQuery` | Send `type: "get"` with `getCommandParameters` and `command='Execute'`; read `Stanza.x`.               |
| Start execution              | `POST /Agent/Xmpp/InformationQuery` | Send `type: "set"` with `executeNodeQuery`, a unique `queryId`, and the submitted form; check `ok`.    |
| Collect results on a backend | `POST /Agent/Xmpp/PopMessages`      | Send `maxCount`; process matching `queryProgress` elements in `Messages[].Content[]` until completion. |
| End the session              | `POST /Agent/Account/Logout`        | Send `{}` with the session JWT.                                                                        |

Include `Content-Type: application/json`, `Accept: application/json`, and your application's URL in `Referer` on every request.
After login, also include `Authorization: Bearer <JWT>`.
The [discovery guide](/reports/quickstart) and [execution guide](/reports/execute-over-http) show complete requests and responses in order.

Browser integrations using `ExecuteReport()` receive completion through the [Agent Events connection](/reports/javascript#endpoints-used-by-the-browser-helpers).
They use `POST /Agent/Xmpp/RegisterEventHandler` and the `/ClientEventsWS` WebSocket instead of backend polling.

## Follow the report lifecycle

1. Sign in and obtain a JWT session token.
2. Resolve the Reports JID to its current full address.
3. List the reports visible to your account.
4. Fetch the selected report's parameter form.
5. Submit the parameters and collect progress until the report completes.
6. Read the returned tables, messages, and objects.

Discovery returns identifiers, not report results. Running a report produces results asynchronously.
There is no universal set of columns: each report defines its own parameters and output.

## Choose your integration

<CardGroup cols={2}>
  <Card title="Start from your backend" icon="server" href="/reports/quickstart">
    Sign in with supplied credentials and discover reports using complete HTTP requests.
  </Card>

  <Card title="Run reports over HTTP" icon="code" href="/reports/execute-over-http">
    Submit a parameter form and collect results from any backend language.
  </Card>

  <Card title="Use the JavaScript helpers" icon="js" href="/reports/javascript">
    Understand the three Reports methods and their assembled results.
  </Card>

  <Card title="Understand responses" icon="table" href="/reports/responses">
    Interpret parameter forms, tables, typed cells, and completion states.
  </Card>
</CardGroup>

Keep shared client credentials and JWTs on your backend. Return only the report data your application needs to its browser users.

<Note>
  `AgentAPI.Reports` is a JavaScript extension built on the Agent API's XMPP messaging resources.
  There is no separate `/Agent/Reports/GetReports` HTTP endpoint. Your HTTP client does not need to open an XMPP connection.
</Note>