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

# Build your first report with Python or JavaScript

> Discover projects, select a measurement, and produce the same small report in either language.

Use the included Python or JavaScript example to discover projects, select a measurement, and produce a JSON report with citation coverage and confidence intervals.

## Before you start

You need an IQRush bearer access token issued for your integration and environment. The examples use that credential; they do not sign you in or refresh tokens. Follow [authentication](/developers/guides/04-authentication) to implement the authorization flow with an OAuth client library. A connected ChatGPT or Claude session does not expose its token for reuse in these scripts.

Use Python or Node.js. The examples use only built-in libraries and were executed with Python 3.12 and Node.js 24. [Download the report starter (ZIP)](/examples/IQRush-Report-Starter.zip). It contains `http_report.py`, `http_report.mjs`, `read_result.py`, `report-example.json`, and a README.

Extract the downloaded starter ZIP and run the commands below from the folder containing `http_report.py` and `http_report.mjs`. If you already followed [HTTP setup](/developers/guides/06-http-quickstart), keep its connection settings and selected IDs; you can skip discovery and go to step 4.

## 1. Configure your connection

Supply these values through your application's secure environment configuration:

| Variable | Value |
| - | - |
| `IQRUSH_API_BASE` | The HTTP base for the environment that issued the token. See [HTTP setup](/developers/guides/06-http-quickstart). |
| `IQRUSH_ACCESS_TOKEN` | The bearer access token issued for this integration. |
| `IQRUSH_PROJECT_ID` | Set this after project discovery. |
| `IQRUSH_RUN_ID` | Optional. Set it to select a particular run. |

Keep the access token out of source files, shared screenshots, and the report itself.

## 2. Find the project

Choose either language. You do not need to run both.

```bash theme={null}
python3 http_report.py --list-projects
```

```bash theme={null}
node http_report.mjs --list-projects
```

The result lists `project_id`, `name`, `workspace_name`, and `status`. Select the intended project and set `IQRUSH_PROJECT_ID` to its exact ID. Names can repeat across workspaces.

## 3. Choose a measurement

```bash theme={null}
python3 http_report.py --list-runs
```

```bash theme={null}
node http_report.mjs --list-runs
```

Read `status`, `completed_at`, `data_ready`, and `cold_path_ready`. Set `IQRUSH_RUN_ID` to a completed run you intend to report. If you omit it, the example selects the first completed, ready run from the newest-first list. It skips a run whose `cold_path_ready` is false. An explicitly selected unready run produces an error; the script does not silently switch to another run.

## 4. Generate the report

```bash theme={null}
python3 http_report.py > report.json
```

```bash theme={null}
node http_report.mjs > report.json
```

The scripts request domain-level stability and owned-domain citation coverage grouped by platform. They preserve proportions and returned interval levels; they do not multiply values by 100 or invent missing values. The report contains project/run context, dates, filters, quality fields, and measurement rows. The starter includes `report-example.json`, a selected-field output from the executed example with private IDs replaced.

## 5. Check the result

| Report field | What to check |
| - | - |
| `run_id`, `completed_at` | The intended measurement and date. |
| `metric`, `metric_unit` | `citation_coverage` and `proportion` for this starter. A value of `0.25` means 25%. |
| `quality.is_converged` | Whether the returned domain-level convergence checks passed. |
| `rows[].group_by_values` | The platform for each row. |
| `rows[].estimate.value` | The measured value; preserve null if unavailable. |
| `rows[].estimate.ci` | The returned lower bound, upper bound, and confidence level. |
| `rows[].estimate.stability` | Row quality, where supplied. It is separate from run convergence. |

A converged run does not make every row or comparison conclusive. Follow [decision-grade measurement](/developers/guides/10-stability) before using the report to recommend an action. The starter stops on reported measurement warnings and unavailable states. Review an empty row list rather than treating it as zero visibility.

## 6. Resolve a failed request

Missing configuration produces a message naming the required variables. An HTTP 401 requires a valid credential or a new authorization flow. Invalid IDs should be replaced with values from discovery. Temporary failures receive bounded retries; a server-requested delay above the example's limit stops the report for a later retry.

See [errors and recovery](/developers/guides/13-errors), then choose a [report recipe](/developers/guides/16-report-recipes) when the first report is working.


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