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

# Generate Report

> Build a report for a date range: visitors, leads, conversion rate, lead quality, top leads, traffic by country, plus a written summary and action plan.

> [!NOTE]
>
> Requires an [API key](https://www.orwel.io/docs/authentication.md) (`orwel_sk_`) with all three scopes: `leads:read`, `visitors:read` and `conversions:read`.

The report always covers the workspace that owns the key. It takes a few seconds because Orwel also writes the analysis (summary, insights and action plan) from the numbers. If the analysis cannot be generated, the response still returns the data with a shorter summary built from it.

## Body

**dateFrom** `string` *required*

Start of the range, ISO 8601 (`2026-10-01`)

**dateTo** `string` *required*

End of the range, ISO 8601 (`2026-10-31`)

**workspaceId** `string`

Optional. When sent it must be the key's own workspace; any other value returns `403 forbidden`.

## Response

**data** `object`

**Report**

**metrics** `object`

`totalVisitors`, `totalLeads`, `conversionRate` and `avgLeadScore` for the range

**leadQualityDistribution** `object`

Leads by quality: `high`, `medium`, `low`, `unknown`

**leadScoreDistribution** `object`

Leads by score: `high` (70 to 100), `medium` (40 to 69), `low` (0 to 39), `unscored`

**conversionsByCode** `object`

Number of conversions per conversion code

**topLeads** `array`

Best leads of the range with name, email, quality, score, source, location and lifecycle stage

**trafficByCountry** `object`

Visitors per country

**lifecycleDistribution** `object`

Identities by stage: `anonymous`, `lead`, `customer`, `churned`, `other`

**analysis** `object`

Written analysis: `executiveSummary`, `keyInsights` (array), `actionPlan` (array), `funnelAnalysis`, `prospectHighlights`

## Errors

| Status | `error` | When |
| - | - | - |
| `400` | `bad_request` | The body is not JSON, `dateFrom` or `dateTo` is missing, or a date is not ISO 8601. |
| `403` | `insufficient_scope` | The key is missing one of the three scopes. |
| `403` | `forbidden` | `workspaceId` is not the key's workspace. |

```bash cURL theme={null}
curl -X POST "https://api.orwel.io/api/v1/reports" \
  -H "Authorization: Bearer orwel_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dateFrom": "2026-10-01", "dateTo": "2026-10-31"}'
```

```json Response theme={null}
{
  "data": {
    "workspaceId": "770e8400-e29b-41d4-a716-446655440002",
    "dateFrom": "2026-10-01",
    "dateTo": "2026-10-31",
    "generatedAt": "2026-11-04T16:18:37.149Z",
    "metrics": {
      "totalVisitors": 2140,
      "totalLeads": 63,
      "conversionRate": 2.94,
      "avgLeadScore": 58
    },
    "leadQualityDistribution": { "high": 12, "medium": 30, "low": 15, "unknown": 6 },
    "leadScoreDistribution": { "high": 14, "medium": 29, "low": 12, "unscored": 8 },
    "conversionsByCode": { "generate_lead": 51, "book_demo": 12 },
    "topLeads": [],
    "trafficByCountry": { "MX": 1320, "US": 610 },
    "lifecycleDistribution": { "anonymous": 1890, "lead": 63, "customer": 9, "churned": 0, "other": 0 },
    "analysis": {
      "executiveSummary": "October brought 63 leads from 2,140 visitors...",
      "keyInsights": ["Most high score leads came from organic search"],
      "actionPlan": ["Follow up the 12 high quality leads this week"],
      "funnelAnalysis": "...",
      "prospectHighlights": "..."
    }
  }
}
```


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