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

# Berichte

> Exportieren Sie einen einmaligen Scan-Bericht oder planen Sie wiederkehrende Berichts-E-Mails.

> [!NOTE]
>
> Die GetQR API befindet sich in der Beta-Phase und steht ausgewählten Workspaces zur Verfügung. Details können sich bis zur allgemeinen Veröffentlichung noch ändern.

Berichte fassen die Scans pro QR-Code für einen abgeschlossenen Tag, eine Woche oder einen Monat zusammen. Exportieren Sie einen Bericht sofort, oder planen Sie einen Bericht, der regelmäßig per E-Mail verschickt wird.

| Methode | Pfad | Beschreibung |
| - | - | - |
| `POST` | `/api/v1/reports` | [Bericht exportieren](#bericht-exportieren) |
| `GET` | `/api/v1/reports/schedules` | [Geplante Berichte auflisten](#geplante-berichte-auflisten) |
| `POST` | `/api/v1/reports/schedules` | [Bericht planen](#bericht-planen) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [Geplanten Bericht aktualisieren](#geplanten-bericht-aktualisieren) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [Geplanten Bericht löschen](#geplanten-bericht-löschen) |

## Header

**Authorization** `string` *required*

`Bearer` gefolgt von Ihrem API-Schlüssel. Siehe [Authentifizierung](https://docs.getqr.com/de/api/authentication.md).

**Content-Type** `string`

`application/json`. Erforderlich bei `POST`- und `PATCH`-Anfragen.

## Umfang

Einmalige und geplante Berichte erwarten beide einen `scope`:

| `scope` | Umfasst | `qrIds` |
| - | - | - |
| `all` | Die QR-Codes in Ihrem Workspace | Weglassen |
| `selected` | Eine ausgewählte Gruppe von QR-Codes | Eine oder mehrere IDs |
| `single` | Genau einen QR-Code | Genau eine ID |

Ein Bericht listet höchstens 50 QR-Codes. Bei `all` sind das die zuletzt erstellten aktiven QR-Codes, pausierte Codes fehlen. Bei `selected` und `single` sind pausierte Codes enthalten. QR-Codes ohne Kurzlink haben keine Scans und werden übersprungen.

## Zeitraum

Der Zeitraum ist immer der zuletzt abgeschlossene, sodass ein Bericht nie die unvollständigen Daten von heute enthält. Seine Grenzen liegen um Mitternacht in der Zeitzone des Berichts.

| `period` oder `frequency` | Umfasst |
| - | - |
| `daily` | Den Vortag |
| `weekly` | Die Vorwoche, Montag bis Sonntag |
| `monthly` | Den vorigen Kalendermonat |

## Bericht exportieren

`POST /api/v1/reports`

Erstellt einen Bericht für den zuletzt abgeschlossenen Zeitraum und liefert ihn in der Antwort.

**scope** `string` *required*

`all`, `selected` oder `single`. Siehe [Umfang](#umfang).

**period** `string` *required*

`daily`, `weekly` oder `monthly`. Siehe [Zeitraum](#zeitraum).

**format** `string` *required*

`json` liefert den Bericht im Antwort-Body. `csv` und `pdf` liefern einen Datei-Download.

**qrIds** `string[]`

Einzubeziehende QR-Codes. Erforderlich bei `selected` (eine oder mehrere IDs) und `single` (genau eine ID). Bei `all` weglassen.

**timezone** `string` (default: UTC)

IANA-Zeitzone, an der die Grenzen des Zeitraums ausgerichtet werden, zum Beispiel `America/New_York`. Eine unbekannte Zeitzone liefert `422`.

**locale** `string` (default: en)

Sprache des PDFs, zum Beispiel `en` oder `de`. Bei einem nicht unterstützten Wert wird Englisch verwendet. Wird von `csv` und `json` ignoriert.

**name** `string`

Titel auf dem PDF, bis zu 40 Zeichen. Wird von `csv` und `json` ignoriert.

### JSON-Antwort

**periodStart** `string`

Erster Tag des Zeitraums, `YYYY-MM-DD`.

**periodEnd** `string`

Erster Tag nach dem Zeitraum, `YYYY-MM-DD`. Der Zeitraum endet um Mitternacht zu Beginn dieses Tages.

**qrs** `object[]`

Ein Eintrag pro QR-Code.

**properties**

**qrId** `string`

ID des QR-Codes.

**name** `string`

Titel des QR-Codes oder `Untitled QR`.

**type** `string`

Typ des QR-Codes, zum Beispiel `website`.

**totalScans** `integer`

Alle Scans im Zeitraum.

**uniqueScans** `integer`

Eindeutige Scans im Zeitraum.

**topGeography** `string`

Ländercode mit den meisten Scans oder `—` ohne Scans.

**topDevice** `string`

Gerät mit den meisten Scans oder `—`.

**topOs** `string`

Betriebssystem mit den meisten Scans oder `—`.

**topBrowser** `string`

Browser mit den meisten Scans oder `—`.

### CSV- und PDF-Antworten

Der Body ist die Datei. `Content-Disposition` benennt sie nach dem Zeitraum, zum Beispiel `report-2026-08-10_2026-08-17.csv`. Die CSV-Datei hat eine Zeile pro QR-Code mit den Spalten `QR ID`, `QR name`, `QR type`, `Total scans`, `Unique scans`, `Top geography`, `Top device`, `Top OS` und `Top browser`.

```bash JSON theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "period": "weekly",
    "format": "json",
    "timezone": "America/New_York"
  }'
```

```bash PDF theme={null}
curl -X POST "https://getqr.com/api/v1/reports" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "all", "period": "monthly", "format": "pdf", "locale": "de" }' \
  --output report.pdf
```

```json 200 theme={null}
{
  "periodStart": "2026-08-10",
  "periodEnd": "2026-08-17",
  "qrs": [
    {
      "qrId": "clw3n7t1x0002ab0d5mqe8pkr",
      "name": "Landing page",
      "type": "website",
      "totalScans": 128,
      "uniqueScans": 96,
      "topGeography": "US",
      "topDevice": "Mobile",
      "topOs": "iOS",
      "topBrowser": "Safari"
    }
  ]
}
```

## Das Objekt des geplanten Berichts

Ein geplanter Bericht wird um Mitternacht in seiner Zeitzone per E-Mail an das Konto geschickt, das ihn erstellt hat.

**id** `string`

ID des geplanten Berichts.

**name** `string | null`

Bezeichnung, die im Betreff der E-Mail und im Dashboard angezeigt wird.

**frequency** `string`

`daily`, `weekly` oder `monthly`.

**scope** `string`

`all`, `selected` oder `single`.

**qrIds** `string[] | null`

QR-Codes, die der Bericht bei den Umfängen `selected` und `single` abdeckt. `null`, wenn keine IDs gesendet wurden.

**filters** `null`

Immer `null`. Reserviert.

**includePdf** `boolean`

Ob der E-Mail ein PDF angehängt wird.

**status** `string`

`active` oder `paused`.

**timezone** `string`

IANA-Zeitzone, an der Versandzeit und Zeitraum ausgerichtet werden.

**locale** `string`

Sprache der E-Mail und des PDFs.

**nextRunAt** `string`

Fälligkeit der nächsten E-Mail, ISO 8601: die nächste Mitternacht (`daily`), der nächste Montag (`weekly`) oder der 1. des nächsten Monats (`monthly`), jeweils in der Zeitzone des Berichts.

**lastRunAt** `string | null`

Versandzeitpunkt der letzten E-Mail, ISO 8601.

**createdAt** `string`

Erstellungsdatum, ISO 8601.

**updatedAt** `string`

Datum der letzten Aktualisierung, ISO 8601.

## Geplante Berichte auflisten

`GET /api/v1/reports/schedules`

Liefert die geplanten Berichte Ihres Workspace, auch die von anderen Mitgliedern erstellten, die neuesten zuerst. Die Liste ist paginiert: siehe [Paginierung](https://docs.getqr.com/de/api/introduction.md#paginierung).

**page** `integer` (default: 1)

Zurückzugebende Seite, 1 oder höher.

**pageSize** `integer` (default: 100)

Ergebnisse pro Seite, 1 bis 100.

```bash cURL theme={null}
curl "https://getqr.com/api/v1/reports/schedules?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "clx8f2k9a0001qk0c8vhd3xyz",
      "name": "Weekly campaign digest",
      "frequency": "weekly",
      "scope": "selected",
      "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr", "clw3n7t1x0004ab0d9rzu2wfh"],
      "filters": null,
      "includePdf": true,
      "status": "active",
      "timezone": "America/New_York",
      "locale": "en",
      "nextRunAt": "2026-08-10T04:00:00.000Z",
      "lastRunAt": "2026-08-03T04:00:12.000Z",
      "createdAt": "2026-07-01T12:34:56.000Z",
      "updatedAt": "2026-07-28T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}
```

## Bericht planen

`POST /api/v1/reports/schedules`

Erstellt einen Bericht, der regelmäßig per E-Mail verschickt wird. `nextRunAt` wird aus Häufigkeit und Zeitzone berechnet.

> [!NOTE]
>
> Ein QR-Code kann pro Häufigkeit nur zu einem geplanten Bericht gehören. Ein überschneidender Zeitplan liefert `409 conflict`.

Ein Bericht mit dem Umfang `all` überschneidet sich mit jedem anderen Bericht derselben Häufigkeit. Pausierte Berichte zählen mit.

**frequency** `string` *required*

Wie oft der Bericht verschickt wird: `daily`, `weekly` oder `monthly`. Legt zugleich den abgedeckten Zeitraum fest. Siehe [Zeitraum](#zeitraum).

**scope** `string` *required*

`all`, `selected` oder `single`. Siehe [Umfang](#umfang).

**timezone** `string` *required*

IANA-Zeitzone, an der Versandzeit und Zeitraum ausgerichtet werden, zum Beispiel `America/New_York`. Eine unbekannte Zeitzone liefert `422`.

**locale** `string` *required*

Sprache der E-Mail und des PDFs, zum Beispiel `en` oder `de`. Bei einem nicht unterstützten Wert wird Englisch verwendet. PDFs in `zh`, `ja`, `ko` und `ar` werden auf Englisch erstellt.

**qrIds** `string[]`

Einzubeziehende QR-Codes. Erforderlich bei `selected` (eine oder mehrere IDs) und `single` (genau eine ID). Jede ID muss ein QR-Code in Ihrem Workspace sein, sonst liefert die Anfrage `404`.

**name** `string`

Bezeichnung, die im Betreff der E-Mail und im Dashboard angezeigt wird, bis zu 40 Zeichen.

**includePdf** `boolean` (default: false)

Eine PDF-Version des Berichts an die E-Mail anhängen.

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/reports/schedules" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly campaign digest",
    "frequency": "weekly",
    "scope": "selected",
    "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
    "includePdf": true,
    "timezone": "America/New_York",
    "locale": "en"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Weekly campaign digest",
  "frequency": "weekly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-08-10T04:00:00.000Z",
  "lastRunAt": null,
  "createdAt": "2026-08-03T12:34:56.000Z",
  "updatedAt": "2026-08-03T12:34:56.000Z"
}
```

## Geplanten Bericht aktualisieren

`PATCH /api/v1/reports/schedules/{id}`

Ändert einen geplanten Bericht oder pausiert ihn und setzt ihn fort. Senden Sie nur die Felder, die Sie ändern möchten, mindestens eines. Eine Änderung der Häufigkeit oder Zeitzone sowie das Fortsetzen eines pausierten Berichts berechnen `nextRunAt` neu. Die Regel „ein Bericht pro Häufigkeit“ gilt weiterhin, daher liefert eine überschneidende Änderung `409`.

**id** `string` *required*

ID des geplanten Berichts. Nehmen Sie sie aus der Antwort der Liste oder der Erstellung.

**status** `string`

`paused` stoppt die E-Mails, ohne den Zeitplan zu löschen. `active` setzt sie fort.

**name** `string`

Bezeichnung, bis zu 40 Zeichen.

**frequency** `string`

`daily`, `weekly` oder `monthly`.

**scope** `string`

`all`, `selected` oder `single`.

**qrIds** `string[]`

Einzubeziehende QR-Codes. Jede ID muss ein QR-Code in Ihrem Workspace sein.

**includePdf** `boolean`

Ein PDF an die E-Mail anhängen.

**timezone** `string`

IANA-Zeitzone.

**locale** `string`

Sprache der E-Mail und des PDFs.

```bash cURL theme={null}
curl -X PATCH "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly campaign digest",
    "frequency": "monthly",
    "status": "active"
  }'
```

```json 200 theme={null}
{
  "id": "clx8f2k9a0001qk0c8vhd3xyz",
  "name": "Monthly campaign digest",
  "frequency": "monthly",
  "scope": "selected",
  "qrIds": ["clw3n7t1x0002ab0d5mqe8pkr"],
  "filters": null,
  "includePdf": true,
  "status": "active",
  "timezone": "America/New_York",
  "locale": "en",
  "nextRunAt": "2026-09-01T04:00:00.000Z",
  "lastRunAt": "2026-08-03T04:00:12.000Z",
  "createdAt": "2026-07-01T12:34:56.000Z",
  "updatedAt": "2026-08-05T10:15:00.000Z"
}
```

## Geplanten Bericht löschen

`DELETE /api/v1/reports/schedules/{id}`

Löscht den Zeitplan und stoppt alle weiteren E-Mails.

> [!WARNING]
>
> Das Löschen eines geplanten Berichts lässt sich nicht rückgängig machen.

**id** `string` *required*

ID des geplanten Berichts.

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/reports/schedules/clx8f2k9a0001qk0c8vhd3xyz" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "clx8f2k9a0001qk0c8vhd3xyz", "deleted": true }
```

## Häufige Probleme

> [accordion] 404 beim Exportieren eines Berichts
>
> Beim Umfang `selected` oder `single` passte keine der `qrIds` zu einem QR-Code mit Kurzlink in Ihrem Workspace. Prüfen Sie die IDs.

> [accordion] 404 "QR not found." beim Planen eines Berichts
>
> Eine der `qrIds` ist kein QR-Code in Ihrem Workspace oder wurde gelöscht. Prüfen Sie die IDs mit [QR-Codes auflisten](https://docs.getqr.com/de/api/endpoints/qr-codes.md).

> [accordion] 409 beim Planen eines Berichts
>
> Einer der QR-Codes gehört bereits zu einem geplanten Bericht mit derselben Häufigkeit, oder ein Bericht dieser Häufigkeit verwendet den Umfang `all`. Bearbeiten oder löschen Sie diesen Bericht, oder wählen Sie eine andere Häufigkeit.

> [accordion] 404 "Scheduled report not found."
>
> Die `id` passt zu keinem geplanten Bericht in Ihrem Workspace. Nehmen Sie sie aus [Geplante Berichte auflisten](#geplante-berichte-auflisten).

> [accordion] Im Bericht fehlen die Scans von heute
>
> Berichte decken nur den zuletzt abgeschlossenen Zeitraum ab. Für aktuelle Zahlen verwenden Sie [Analytics](https://docs.getqr.com/de/api/endpoints/analytics.md).

## Wie geht es weiter?

> [card] [Analytics](https://docs.getqr.com/de/api/endpoints/analytics.md)

> [card] [Geplante Berichte in der App](https://docs.getqr.com/de/analytics/scheduled-reports.md)

> [card] [Berichte lesen](https://docs.getqr.com/de/analytics/reading-reports.md)

> [card] [Fehler](https://docs.getqr.com/de/api/errors.md)


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