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

# レポート

> 単発のスキャンレポートをエクスポートしたり、定期的なレポートメールを予約したりします。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

レポートは、終了した 1 日、1 週間、1 か月について、QR コードごとのスキャンをまとめたものです。すぐにエクスポートすることも、定期的にメールで送られるレポートを予約することもできます。

| メソッド | パス | 説明 |
| - | - | - |
| `POST` | `/api/v1/reports` | [レポートをエクスポートする](#レポートをエクスポートする) |
| `GET` | `/api/v1/reports/schedules` | [定期レポートを一覧表示する](#定期レポートを一覧表示する) |
| `POST` | `/api/v1/reports/schedules` | [レポートを予約する](#レポートを予約する) |
| `PATCH` | `/api/v1/reports/schedules/{id}` | [定期レポートを更新する](#定期レポートを更新する) |
| `DELETE` | `/api/v1/reports/schedules/{id}` | [定期レポートを削除する](#定期レポートを削除する) |

## ヘッダー

**Authorization** `string` *required*

`Bearer` の後に API キーを続けます。[認証](https://docs.getqr.com/ja/api/authentication.md) をご覧ください。

**Content-Type** `string`

`application/json`。`POST` と `PATCH` のリクエストでは必須です。

## 対象範囲

単発のレポートと定期レポートは、どちらも `scope` を受け付けます。

| `scope` | 対象 | `qrIds` |
| - | - | - |
| `all` | ワークスペースの QR コード | 省略 |
| `selected` | 選択した QR コード | 1 つ以上の ID |
| `single` | 1 つの QR コード | ちょうど 1 つの ID |

1 つのレポートに含まれる QR コードは最大 50 個です。`all` の場合は、最近作成された有効な QR コードが対象になり、一時停止中のコードは除外されます。`selected` と `single` の場合は、一時停止中のコードも含まれます。短縮リンクのない QR コードにはスキャンがないため、スキップされます。

## 期間

期間は常に直近の終了した期間なので、レポートに今日の途中までのデータが含まれることはありません。期間の境界は、レポートのタイムゾーンにおける午前 0 時です。

| `period` または `frequency` | 対象 |
| - | - |
| `daily` | 前日 |
| `weekly` | 前週（月曜日〜日曜日） |
| `monthly` | 前月 |

## レポートをエクスポートする

`POST /api/v1/reports`

直近の終了した期間のレポートを作成し、レスポンスで返します。

**scope** `string` *required*

`all`、`selected`、`single`。[対象範囲](#対象範囲) をご覧ください。

**period** `string` *required*

`daily`、`weekly`、`monthly`。[期間](#期間) をご覧ください。

**format** `string` *required*

`json` はレポートをレスポンスボディで返します。`csv` と `pdf` はファイルのダウンロードを返します。

**qrIds** `string[]`

対象にする QR コード。`selected`（1 つ以上の ID）と `single`（ちょうど 1 つの ID）では必須です。`all` では省略してください。

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

期間の境界を揃える IANA タイムゾーン。例：`America/New_York`。不明なタイムゾーンは `422` を返します。

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

PDF の言語。例：`en`、`de`。サポートされていない値は英語になります。`csv` と `json` では無視されます。

**name** `string`

PDF に表示されるタイトル。最大 40 文字。`csv` と `json` では無視されます。

### JSON のレスポンス

**periodStart** `string`

期間の初日（`YYYY-MM-DD`）。

**periodEnd** `string`

期間の翌日（`YYYY-MM-DD`）。期間はこの日の午前 0 時に終わります。

**qrs** `object[]`

QR コードごとに 1 件。

**properties**

**qrId** `string`

QR コードの ID。

**name** `string`

QR コードのタイトル、または `Untitled QR`。

**type** `string`

QR コードの種類。例：`website`。

**totalScans** `integer`

期間内の総スキャン数。

**uniqueScans** `integer`

期間内のユニークスキャン数。

**topGeography** `string`

スキャンが最も多い国のコード。スキャンがない場合は `—`。

**topDevice** `string`

スキャンが最も多いデバイス、または `—`。

**topOs** `string`

スキャンが最も多い OS、または `—`。

**topBrowser** `string`

スキャンが最も多いブラウザ、または `—`。

### CSV と PDF のレスポンス

ボディはファイルそのものです。`Content-Disposition` では、期間にちなんだファイル名が付きます。例：`report-2026-08-10_2026-08-17.csv`。CSV は QR コードごとに 1 行で、列は `QR ID`、`QR name`、`QR type`、`Total scans`、`Unique scans`、`Top geography`、`Top device`、`Top OS`、`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"
    }
  ]
}
```

## 定期レポートオブジェクト

定期レポートは、作成したアカウントに、そのタイムゾーンの午前 0 時にメールで送られます。

**id** `string`

定期レポートの ID。

**name** `string | null`

メールの件名とダッシュボードに表示されるラベル。

**frequency** `string`

`daily`、`weekly`、`monthly`。

**scope** `string`

`all`、`selected`、`single`。

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

`selected` と `single` の対象範囲で、レポートの対象になる QR コード。ID が送られなかった場合は `null`。

**filters** `null`

常に `null`。予約済みのフィールドです。

**includePdf** `boolean`

メールに PDF が添付されるかどうか。

**status** `string`

`active` または `paused`。

**timezone** `string`

送信時刻と期間を揃える IANA タイムゾーン。

**locale** `string`

メールと PDF の言語。

**nextRunAt** `string`

次のメールの送信予定日時（ISO 8601）。レポートのタイムゾーンで、次の午前 0 時（`daily`）、次の月曜日（`weekly`）、翌月 1 日（`monthly`）です。

**lastRunAt** `string | null`

最後にメールが送信された日時（ISO 8601）。

**createdAt** `string`

作成日時（ISO 8601）。

**updatedAt** `string`

最終更新日時（ISO 8601）。

## 定期レポートを一覧表示する

`GET /api/v1/reports/schedules`

ワークスペースの定期レポートを、他のメンバーが作成したものも含めて新しい順に返します。一覧はページ分割されます。[ページネーション](https://docs.getqr.com/ja/api/introduction.md#ページネーション) をご覧ください。

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

返すページ。1 以上。

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

1 ページあたりの件数。1〜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 }
}
```

## レポートを予約する

`POST /api/v1/reports/schedules`

定期的にメールで送られるレポートを作成します。`nextRunAt` は頻度とタイムゾーンから計算されます。

> [!NOTE]
>
> 1 つの QR コードは、頻度ごとに 1 つの定期レポートにしか含められません。重複するスケジュールは `409 conflict` を返します。

`all` の対象範囲を持つレポートは、同じ頻度の他のすべてのレポートと重複します。一時停止中のレポートもカウントされます。

**frequency** `string` *required*

レポートの送信頻度：`daily`、`weekly`、`monthly`。対象期間もこれで決まります。[期間](#期間) をご覧ください。

**scope** `string` *required*

`all`、`selected`、`single`。[対象範囲](#対象範囲) をご覧ください。

**timezone** `string` *required*

送信時刻と期間を揃える IANA タイムゾーン。例：`America/New_York`。不明なタイムゾーンは `422` を返します。

**locale** `string` *required*

メールと PDF の言語。例：`en`、`de`。サポートされていない値は英語になります。`zh`、`ja`、`ko`、`ar` の PDF は英語でレンダリングされます。

**qrIds** `string[]`

対象にする QR コード。`selected`（1 つ以上の ID）と `single`（ちょうど 1 つの ID）では必須です。すべての ID がワークスペースの QR コードである必要があり、そうでない場合は `404` を返します。

**name** `string`

メールの件名とダッシュボードに表示されるラベル。最大 40 文字。

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

レポートの PDF 版をメールに添付します。

```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"
}
```

## 定期レポートを更新する

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

定期レポートを変更するか、一時停止・再開します。変更したいフィールドだけを、1 つ以上送ってください。頻度やタイムゾーンを変更するか、一時停止中のレポートを再開すると、`nextRunAt` が再計算されます。頻度ごとに 1 レポートというルールは引き続き適用されるため、重複する変更は `409` を返します。

**id** `string` *required*

定期レポートの ID。一覧または作成のレスポンスから取得します。

**status** `string`

`paused` はスケジュールを削除せずにメールを停止します。`active` はメールを再開します。

**name** `string`

ラベル。最大 40 文字。

**frequency** `string`

`daily`、`weekly`、`monthly`。

**scope** `string`

`all`、`selected`、`single`。

**qrIds** `string[]`

対象にする QR コード。すべての ID がワークスペースの QR コードである必要があります。

**includePdf** `boolean`

メールに PDF を添付します。

**timezone** `string`

IANA タイムゾーン。

**locale** `string`

メールと PDF の言語。

```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"
}
```

## 定期レポートを削除する

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

スケジュールを削除し、以降のメールをすべて停止します。

> [!WARNING]
>
> 定期レポートの削除は元に戻せません。

**id** `string` *required*

定期レポートの ID。

```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 }
```

## よくある問題

> [accordion] レポートのエクスポート時に 404 になる
>
> `selected` または `single` の対象範囲で、`qrIds` のどれもワークスペース内の短縮リンクを持つ QR コードに一致しませんでした。ID を確認してください。

> [accordion] レポートの予約時に 404 "QR not found."
>
> `qrIds` のいずれかがワークスペースの QR コードではないか、削除されています。[QR コードを一覧表示する](https://docs.getqr.com/ja/api/endpoints/qr-codes.md) で ID を確認してください。

> [accordion] レポートの予約時に 409 になる
>
> QR コードのいずれかがすでに同じ頻度の定期レポートに含まれているか、その頻度のレポートが `all` の対象範囲を使っています。そのレポートを編集または削除するか、別の頻度を選んでください。

> [accordion] 404 "Scheduled report not found."
>
> その `id` は、ワークスペースの定期レポートに一致しません。[定期レポートを一覧表示する](#定期レポートを一覧表示する) から取得してください。

> [accordion] レポートに今日のスキャンが含まれていない
>
> レポートは直近の終了した期間だけを対象にします。リアルタイムの数値には [分析](https://docs.getqr.com/ja/api/endpoints/analytics.md) を使ってください。

## 次のステップ

> [card] [分析](https://docs.getqr.com/ja/api/endpoints/analytics.md)

> [card] [アプリでの定期レポート](https://docs.getqr.com/ja/analytics/scheduled-reports.md)

> [card] [レポートの読み方](https://docs.getqr.com/ja/analytics/reading-reports.md)

> [card] [エラー](https://docs.getqr.com/ja/api/errors.md)


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