> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/itp-guide/api/data-export.md).

# データのエクスポート

受講が終わったトレーニングのセッションのデータを、機械で読み取れる形式で取り出します。お客様の BI ツールや社内の記録用システムなどに取り込むためのデータを、JSON 形式または xAPI 形式で出力できます。

セッションのデータは2種類の形で取り出せます。

* **サマリー**: 主な項目だけ
* **詳細**: すべての項目（評価・会話スキル・コーチングフィードバックの要約・文字起こしなど）

{% hint style="info" %}
xAPI（Experience API）は、学習の記録をやり取りするための標準仕様です。xAPI 形式で出力できるのはサマリーだけです。取り込み先のシステムが本製品の出力をそのまま受け付けるかどうかは、取り込み先の仕様をご確認ください。
{% endhint %}

## エンドポイント一覧

| メソッド  | エンドポイント                    | 内容                                                   |
| ----- | -------------------------- | ---------------------------------------------------- |
| `GET` | `/export/sessions/summary` | [セッションのサマリーをエクスポートする](#export-session-summary)（主な項目） |
| `GET` | `/export/sessions/details` | [セッションの詳細をエクスポートする](#export-session-details)（すべての項目） |

すべてのパスは、ベースURL `https://training.uneeq.io/api/external/v1/organization/{orgID}` からの相対パスです。コード例の `BASE_URL`・`headers`・`API_KEY` の用意のしかたは [API の概要](https://docs.digitalhumans.jp/itp-guide/api.md) をご覧ください。

## 認証

エクスポートのリクエストには、すべて `Authorization` ヘッダーに Bearer トークン（APIキー）が必要です。APIキーの用意のしかたは [認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md) をご覧ください。

```
Authorization: Bearer your-api-key-here
```

***

## セッションのサマリーをエクスポートする <a href="#export-session-summary" id="export-session-summary"></a>

トレーニングのセッションを、主な項目だけに絞った形で取得します。

```
GET /export/sessions/summary
```

### クエリパラメーター <a href="#query-parameters" id="query-parameters"></a>

| パラメーター      | 型       | 既定値         | 説明                                                                                                                  |
| ----------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `format`    | string  | `json`      | 出力形式。`json` または `xapi`（xAPI はサマリーのみ）。空の値は `json` として扱われます                                                           |
| `time_from` | string  | （なし）        | 対象にするセッションの**開始**日時の下限（RFC 3339）                                                                                    |
| `time_to`   | string  | （なし）        | 対象にするセッションの**開始**日時の上限（RFC 3339）。指定した日時を**含みます**                                                                    |
| `limit`     | integer | `1000`      | 返す最大件数（`1`〜`10000`）。`0` 以下を指定すると既定の `1000` になり、`10000` を超えると `400` になります。整数でない値は `400` です                           |
| `offset`    | integer | `0`         | 読み飛ばす件数。負の値は `0` として扱われます。整数でない値は `400` です                                                                          |
| `status`    | string  | `completed` | セッションの状態をカンマ区切りで指定するか、`all` を単独で指定します。大文字・小文字は区別され、知らない値を指定すると `400` になります（[セッションの状態の値](#session-status-values)を参照） |

{% hint style="info" %}
**日時の絞り込みは、セッションの開始日時が基準です。**\
`time_from` と `time_to` は、どちらもセッションの開始日時（レスポンスの `started_at`）と照らし合わせます。`time_to` は指定した日時を含みます。
{% endhint %}

### レスポンスのフィールド

| フィールド                 | 型                | 説明                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id`          | string           | セッションを一意に識別する ID                                                                                                                                                                                                                                                                                                                  |
| `user_email`          | string           | 受講者のメールアドレス                                                                                                                                                                                                                                                                                                                       |
| `user_name`           | string           | 受講者の表示名                                                                                                                                                                                                                                                                                                                           |
| `training_name`       | string           | トレーニング名                                                                                                                                                                                                                                                                                                                           |
| `training_id`         | string           | トレーニングを一意に識別する ID                                                                                                                                                                                                                                                                                                                 |
| `scenario_type`       | string           | 会話型のセッションは `ROLE_PLAY`、Q\&Aシナリオのセッションは `TECHNICAL_ACUMEN`、作成者本人だけの非公開の練習用ロールプレイは `PRACTICE`。詳細のエクスポートでどのフィールドに値が入るかは、この値で決まります。値は今後追加される可能性があります。知らない値はエラーとせず、「お客様のシステムでは扱わない種別」として処理してください                                                                                                                                       |
| `status`              | string           | セッションの状態（例: `completed`、`analyzing`）                                                                                                                                                                                                                                                                                              |
| `score_percentage`    | float            | セッションの点数（`0`〜`100`）                                                                                                                                                                                                                                                                                                               |
| `duration_seconds`    | float            | セッションの長さ（秒）                                                                                                                                                                                                                                                                                                                       |
| `started_at`          | datetime         | セッションの開始日時（RFC 3339）                                                                                                                                                                                                                                                                                                              |
| `completed_at`        | datetime         | セッションの完了日時（RFC 3339）                                                                                                                                                                                                                                                                                                              |
| `endorsement_level`   | string           | この受講者とトレーニングの組み合わせでの合格認定の状態。`NONE`（合格認定されていない）または `STANDARD`（合格認定済み）。今後レベルが追加される可能性があるため、`NONE` 以外は「何らかのレベルで合格認定済み」として扱ってください                                                                                                                                                                                                     |
| `endorsed_at`         | datetime \| null | 合格認定された日時（RFC 3339）。合格認定されていない場合は `null`                                                                                                                                                                                                                                                                                          |
| `manually_overridden` | boolean（任意）      | マネージャーがこのセッションの点数を1つ以上上書きしている場合は `true`、AI による採点だけの場合は `false`。点数の手動上書き機能を使っていない組織では、フィールドごと含まれません                                                                                                                                                                                                                                |
| `overridden_by`       | string（任意）       | 現在の上書きを行ったマネージャーのメールアドレス。現在上書きされているセッションにだけ含まれます。受講者を表す `user_email` とは別のものです                                                                                                                                                                                                                                                     |
| `override_reason`     | string（任意）       | 現在の上書きについてマネージャーが入力した理由。現在上書きされているセッションにだけ含まれます                                                                                                                                                                                                                                                                                   |
| `override_date_time`  | datetime（任意）     | 現在の上書きが行われた日時（RFC 3339。常に UTC からの時差付き。例: `2026-02-15T09:12:30Z`）。現在上書きされているセッションにだけ含まれます                                                                                                                                                                                                                                          |
| `integrity_level`     | string（任意）       | 合格認定を求めるトレーニングの `TECHNICAL_ACUMEN` セッションについての、受講の適正さを信号機の3色で表した評価。`GREEN`、`ORANGE`、`RED` のいずれかで、セッション中の挙動（コピーの試みがブロックされた、ウィンドウからフォーカスが外れた、回答が遅れた）から判定されます。適正さのデータが記録されていないセッション（ロールプレイのセッション、合格認定を求めないトレーニング、この機能の導入前のセッション）では含まれません。不正があったと断定するものではありません。回答の内容と合わせて確認してください。値は今後追加される可能性があります。知らない値は「何らかのレベルで注意が付いている」として扱ってください |

本ページでは、endorsement（所定の点数に達したことを認める仕組み）を、画面の表記に合わせて「合格認定」と書きます。

{% hint style="info" %}
**点数の手動上書き**\
`manually_overridden`・`overridden_by`・`override_reason`・`override_date_time` は、点数の手動上書き機能が有効な組織でだけ出力されます。マネージャーによる上書きが有効な間は、`score_percentage` と評価基準ごとの点数は、上書き後の値になります。
{% endhint %}

### レスポンス

**200 OK:**

```json
{
  "version": "1.0",
  "sessions": [
    {
      "session_id": "abc-123",
      "user_email": "jane@example.com",
      "user_name": "Jane Smith",
      "training_name": "Product Demo Pitch",
      "training_id": "train-1",
      "scenario_type": "ROLE_PLAY",
      "status": "completed",
      "score_percentage": 82.5,
      "duration_seconds": 345.0,
      "started_at": "2026-02-15T09:00:00Z",
      "completed_at": "2026-02-15T09:05:45Z",
      "endorsement_level": "STANDARD",
      "endorsed_at": "2026-02-15T09:05:45Z",
      "manually_overridden": true,
      "overridden_by": "manager@example.com",
      "override_reason": "Adjusted Objection Handling after manager review",
      "override_date_time": "2026-02-15T09:12:30Z",
      "integrity_level": "GREEN"
    }
  ],
  "total": 1
}
```

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/export/sessions/summary?format=json&time_from=2026-01-01T00:00:00Z&time_to=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

BASE_URL = "https://training.uneeq.io/api/external/v1/organization/{orgID}"
headers = {"Authorization": "Bearer your-api-key"}

response = requests.get(
    f"{BASE_URL}/export/sessions/summary",
    headers=headers,
    params={
        "format": "json",
        "time_from": "2026-01-01T00:00:00Z",
        "time_to": "2026-03-01T00:00:00Z"
    }
)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const BASE_URL = 'https://training.uneeq.io/api/external/v1/organization/{orgID}';
const API_KEY = 'your-api-key';

const params = new URLSearchParams({
  format: 'json',
  time_from: '2026-01-01T00:00:00Z',
  time_to: '2026-03-01T00:00:00Z'
});

const response = await fetch(
  `${BASE_URL}/export/sessions/summary?${params}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const data = await response.json();
```

{% endtab %}
{% endtabs %}

***

## セッションの詳細をエクスポートする <a href="#export-session-details" id="export-session-details"></a>

トレーニングのセッションを、すべての項目付きで取得します。評価、会話スキル、コーチングフィードバックの要約、文字起こしも含まれます。

```
GET /export/sessions/details
```

### クエリパラメーター

| パラメーター      | 型       | 既定値         | 説明                                                                                        |
| ----------- | ------- | ----------- | ----------------------------------------------------------------------------------------- |
| `format`    | string  | `json`      | 出力形式。`json` のみ（詳細は xAPI に対応していません）                                                        |
| `time_from` | string  | （なし）        | 対象にするセッションの**開始**日時の下限（RFC 3339）                                                          |
| `time_to`   | string  | （なし）        | 対象にするセッションの**開始**日時の上限（RFC 3339）。指定した日時を**含みます**                                          |
| `limit`     | integer | `1000`      | 返す最大件数（`1`〜`10000`）。`0` 以下を指定すると既定の `1000` になり、`10000` を超えると `400` になります。整数でない値は `400` です |
| `offset`    | integer | `0`         | 読み飛ばす件数。負の値は `0` として扱われます。整数でない値は `400` です                                                |
| `status`    | string  | `completed` | セッションの状態をカンマ区切りで指定するか、`all` を単独で指定します。大文字・小文字は区別され、知らない値を指定すると `400` になります                |

{% hint style="warning" %}
**重要:** `xapi` 形式は**サマリーでしか使えません**。詳細のエンドポイントで xAPI を指定すると `400` エラーになります。
{% endhint %}

### レスポンスのフィールド

[サマリー](#export-session-summary)のフィールドがすべて含まれ、さらに次のフィールドが加わります。

| フィールド                       | 型             | 説明                                                                                                   |
| --------------------------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| `locale`                    | string        | **廃止予定**。`language_code` を使ってください。受講者がセッションで使った言語のロケール（例: `en-US`）。互換性のために引き続き返されます                  |
| `language_code`             | string        | 受講者がセッションで使った言語の基本の言語コード（例: `en`、`fr`、`es`）                                                          |
| `enhanced_analysis`         | boolean       | セッションが映像を使う拡張分析で分析された場合は `true`                                                                      |
| `assessments`               | array \| null | コーチングフィードバックの評価結果（[評価結果オブジェクト](#assessment-object)を参照）。セッションにコーチングフィードバックが無い場合は `null`               |
| `summary_did_well`          | string        | 受講者がよくできた点の総括                                                                                        |
| `summary_needs_improvement` | string        | 改善が必要な点の総括                                                                                           |
| `conversation_skills`       | array         | 会話スキルの指標（[会話スキルオブジェクト](#conversation-skill-object)を参照）。`TECHNICAL_ACUMEN` のセッションでは常に `[]`            |
| `transcript`                | array \| null | 会話の文字起こし（[文字起こしの要素オブジェクト](#transcript-entry-object)を参照）。文字起こしが記録されていないセッションでは `null`                 |
| `questions`                 | array         | 採点された質問（[質問オブジェクト](#question-object)を参照）。`TECHNICAL_ACUMEN` のセッションにだけ含まれ、`ROLE_PLAY` ではフィールドごと含まれません |

{% hint style="warning" %}
**`locale` は廃止予定です。**\
セッションの言語の判定には `language_code` を使ってください。`locale` は互換性のために残されていますが、地域の違い（例: `en-GB` と `en-US`）は受講者ではなくシナリオの言語設定で決まるため、言語を判定する値としては信頼できません。今後削除される予定です。削除の時期については、[弊社にお問い合わせください](https://www.digitalhumans.com/jp/contact)。
{% endhint %}

{% hint style="warning" %}
**`assessments` と `transcript` は `null` になることがあります。**\
セッションにコーチングフィードバックや文字起こしが無い場合、どちらも空の配列ではなく `null` で返ります。たとえば、分析が終わる前にエクスポートした場合です。繰り返し処理をする前に、両方とも `null` かどうかを確認してください。
{% endhint %}

{% hint style="info" %}
**レスポンスの形は `scenario_type` によって2通りです。**\
`TECHNICAL_ACUMEN` のセッションは会話ではなく、採点される質問の集まりです。そのため、`questions` に質問ごとの結果が入り、`conversation_skills` は空の配列になります。\
`ROLE_PLAY` のセッションは逆で、`conversation_skills` に値が入り、`questions` は含まれません。\
まず `scenario_type` を読んで処理を分けてください。`PRACTICE` のセッションは会話型で、`ROLE_PLAY` と同じ形です。`TECHNICAL_ACUMEN` だけを明示的に分岐させ、それ以外の値はすべて会話型として扱うと、今後種別が追加されてもクライアントが壊れません。
{% endhint %}

### 評価結果オブジェクト <a href="#assessment-object" id="assessment-object"></a>

`assessments` 配列の各要素は、コーチングフィードバックの評価基準1つ分の結果です。

| フィールド               | 型                | 説明                               |
| ------------------- | ---------------- | -------------------------------- |
| `name`              | string           | 評価基準の名前（例: "Active Listening"）   |
| `score`             | float            | 評価基準の点数（`0`〜`100`。上書きがあれば上書き後の値） |
| `summary`           | string           | 評価の短い要約                          |
| `did_well`          | string           | 受講者がよくできた点                       |
| `needs_improvement` | string           | 改善が必要な点                          |
| `suggestions`       | array of strings | 具体的な改善の提案                        |

### 質問オブジェクト <a href="#question-object" id="question-object"></a>

`questions` 配列の各要素は、Q\&Aシナリオ（`TECHNICAL_ACUMEN`）のセッションで採点された質問1問分の結果です。

| フィールド               | 型               | 説明                                                                                                      |
| ------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| `question_id`       | string          | 質問を一意に識別する ID                                                                                           |
| `question`          | string          | 質問文                                                                                                     |
| `answer`            | string \| null  | 受講者の回答。回答しなかった場合や、何も話さないうちに制限時間が切れた場合は `null`                                                           |
| `order_asked`       | integer         | このセッションで何番目に出題されたか                                                                                      |
| `score`             | integer \| null | 回答の点数。採点はセッションの終了時に行われるため、回答済みでもまだ採点されていない質問は `0` ではなく `null` になります。何も話さないうちに制限時間が切れた質問は、採点後に `0` になります |
| `summary`           | string          | 回答の短い要約                                                                                                 |
| `did_well`          | string          | 受講者がよくできた点                                                                                              |
| `needs_improvement` | string          | 改善が必要な点                                                                                                 |

### 会話スキルオブジェクト <a href="#conversation-skill-object" id="conversation-skill-object"></a>

`conversation_skills` 配列の各要素は、会話スキルの指標1つ分です。

| フィールド        | 型      | 説明                                                                |
| ------------ | ------ | ----------------------------------------------------------------- |
| `name`       | string | 指標の名前（例: "Filler Words"、"Talk Speed"、"Body Language"）             |
| `score`      | float  | 指標の値                                                              |
| `score_type` | string | `score` の読み方。`percentage`、`value`、`star_rating`、`pass_fail` のいずれか |
| `summary`    | string | 補足の説明（任意。例: "28 seconds"）                                         |

指標には次のものがあります。

| 指標（`name`）          | 内容                    |
| ------------------- | --------------------- |
| `Filler Words`      | つなぎ言葉の指標              |
| `Talk Speed`        | 話速の指標                 |
| `Listen Ratio`      | 聞く比率。画面の「話す・聞く比率」（下記） |
| `Longest Monologue` | 最長の独話の指標              |

すべてのセッションに、上の4つの指標が（取得できた場合に）含まれます。映像を使って分析されたセッション（拡張分析）には、さらに Body Language、Facial Expression、Positioning、Conversation Flow、Tone of Voice などのスキル評価が含まれます。

{% hint style="warning" %}
**Talk Speed（話速）と Filler Words（つなぎ言葉）について**\
英語の会話を前提にした指標で、日本語の会話では正しく計測されない場合があります。評価には使わないでください。
{% endhint %}

{% hint style="info" %}
**Listen Ratio（聞く比率）**\
会話の時間のうち、受講者が聞いていた（デジタルヒューマンが話していた）時間の割合です。`avatar_talk_time / (avatar_talk_time + user_talk_time)` で計算されます。たとえば `0.60` は、会話の60%の時間をデジタルヒューマンが話していたことを表します。\
画面には「話す・聞く比率」という指標があり、話す時間と聞く時間のバランスを示します。
{% endhint %}

### 文字起こしの要素オブジェクト <a href="#transcript-entry-object" id="transcript-entry-object"></a>

`transcript` 配列の各要素は、会話の発言1つ分です。

| フィールド       | 型      | 説明                                       |
| ----------- | ------ | ---------------------------------------- |
| `role`      | string | 話者の種類。`user`（受講者）または `avatar`（デジタルヒューマン） |
| `person`    | string | 話者の表示名                                   |
| `message`   | string | 整えた発言の文章                                 |
| `timestamp` | string | 会話の開始からの経過時間（`MM:SS`）                    |

### レスポンス

**200 OK:**

```json
{
  "version": "1.0",
  "sessions": [
    {
      "session_id": "abc-123",
      "training_name": "Product Demo Pitch",
      "training_id": "train-1",
      "user_email": "jane@example.com",
      "user_name": "Jane Smith",
      "scenario_type": "ROLE_PLAY",
      "status": "completed",
      "score_percentage": 82.5,
      "duration_seconds": 345.0,
      "locale": "en-US",
      "language_code": "en",
      "enhanced_analysis": false,
      "started_at": "2026-02-15T09:00:00Z",
      "completed_at": "2026-02-15T09:05:45Z",
      "endorsement_level": "STANDARD",
      "endorsed_at": "2026-02-15T09:05:45Z",
      "manually_overridden": true,
      "overridden_by": "manager@example.com",
      "override_reason": "Adjusted Objection Handling after manager review",
      "override_date_time": "2026-02-15T09:12:30Z",
      "integrity_level": "GREEN",
      "assessments": [
        {
          "name": "Active Listening",
          "score": 88.0,
          "summary": "Strong listening skills demonstrated throughout",
          "did_well": "Good paraphrasing and acknowledgment of concerns",
          "needs_improvement": "Ask more follow-up questions to deepen understanding",
          "suggestions": [
            "Use open-ended questions after key statements",
            "Paraphrase customer concerns before responding"
          ]
        }
      ],
      "summary_did_well": "Overall strong communication skills with good rapport building",
      "summary_needs_improvement": "Work on closing techniques and handling price objections",
      "conversation_skills": [
        { "name": "Filler Words", "score": 3.2, "score_type": "percentage", "summary": "" },
        { "name": "Talk Speed", "score": 145.0, "score_type": "value", "summary": "145 words per minute" },
        { "name": "Listen Ratio", "score": 0.42, "score_type": "percentage", "summary": "" },
        { "name": "Longest Monologue", "score": 28.0, "score_type": "value", "summary": "28 seconds" }
      ],
      "transcript": [
        { "role": "avatar", "person": "Sales Coach", "message": "Welcome! Tell me about our product.", "timestamp": "00:00" },
        { "role": "user", "person": "Jane Smith", "message": "Sure, our product helps teams collaborate more effectively.", "timestamp": "00:05" }
      ]
    }
  ],
  "total": 1
}
```

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/export/sessions/details?limit=100" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    f"{BASE_URL}/export/sessions/details",
    headers=headers,
    params={"limit": 100}
)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  `${BASE_URL}/export/sessions/details?limit=100`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const data = await response.json();
```

{% endtab %}
{% endtabs %}

***

## セッションの状態の値 <a href="#session-status-values" id="session-status-values"></a>

| 値            | 説明                                                                     |
| ------------ | ---------------------------------------------------------------------- |
| `started`    | セッションが開始され、まだ完了していない                                                   |
| `generating` | AI がセッションの内容を生成している                                                    |
| `analyzing`  | 採点のためにセッションを分析している                                                     |
| `completed`  | セッションが正常に完了した（絞り込みの既定値）                                                |
| `invalid`    | セッションが無効とされた                                                           |
| `abandoned`  | 受講者がセッションを途中でやめた                                                       |
| `fatal`      | セッションで致命的なエラーが起きた                                                      |
| `error`      | セッションで回復可能なエラーが起きた                                                     |
| `all`        | 上のすべての状態を含む特別な値。単独でのみ使えます。ほかの値と組み合わせる（例: `all,completed`）と `400` になります |

値は大文字・小文字を区別し、完全に一致する必要があります。それ以外の値を指定すると、`400` と本文 `{"message": "invalid session status filter"}` が返ります。

***

## 出力形式

### JSON

JSON のレスポンスは、バージョン付きの外枠（エンベロープ）に入っています。

```json
{
  "version": "1.0",
  "sessions": [...],
  "total": 42
}
```

| フィールド      | 型       | 説明                                   |
| ---------- | ------- | ------------------------------------ |
| `version`  | string  | レスポンスのバージョン（現在は `1.0`）               |
| `sessions` | array   | セッションの記録の配列                          |
| `total`    | integer | 条件に合う記録の総数（`X-Total-Count` ヘッダーと同じ値） |

### xAPI（サマリーのみ）

各セッションは、[Experience API の仕様](https://github.com/adlnet/xAPI-Spec)に沿った xAPI ステートメントに変換されます。`success` は、完了したセッションでは `true`、それ以外の状態では `false` です。

**動詞（verb）の対応:** xAPI の動詞は、セッションの状態から決まります。

| セッションの状態                           | xAPI の動詞      |
| ---------------------------------- | ------------- |
| `completed`                        | `completed`   |
| `started`、`generating`、`analyzing` | `attempted`   |
| `abandoned`、`invalid`              | `abandoned`   |
| `error`、`fatal`                    | `failed`      |
| （上記以外）                             | `experienced` |

**タイムスタンプ:** セッションの `completed_at` を使います。完了していないセッションでは `started_at` を使います。

**点数の換算:**

* `scaled`: 点数を100で割った値（例: 82.5 → 0.825）
* `raw`: 元の点数
* `min`: 0、`max`: 100

**長さ:** ISO 8601 の形式です（例: 345秒 → `PT5M45S`、3661秒 → `PT1H1M1S`）。0の要素は省略されます。ただし、長さが0秒の場合は `PT0S` になります。

**xAPI ステートメントの例:**

```json
[
  {
    "actor": {
      "mbox": "mailto:jane@example.com",
      "name": "Jane Smith"
    },
    "verb": {
      "id": "http://adlnet.gov/expapi/verbs/completed",
      "display": { "en-US": "completed" }
    },
    "object": {
      "id": "https://training.digitalhumans.com/training/train-1",
      "definition": {
        "name": { "en-US": "Product Demo Pitch" },
        "type": "http://adlnet.gov/expapi/activities/course"
      }
    },
    "result": {
      "score": {
        "scaled": 0.825,
        "raw": 82.5,
        "min": 0,
        "max": 100
      },
      "duration": "PT5M45S",
      "success": true
    },
    "timestamp": "2026-02-15T09:05:45Z"
  }
]
```

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/export/sessions/summary?format=xapi" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    f"{BASE_URL}/export/sessions/summary",
    headers=headers,
    params={"format": "xapi"}
)
statements = response.json()
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  `${BASE_URL}/export/sessions/summary?format=xapi`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const statements = await response.json();
```

{% endtab %}
{% endtabs %}

***

## ページ分割

件数が多い場合は、`limit` と `offset` で分けて取得します。レスポンスヘッダーの `X-Total-Count` に、条件に合う記録の総数（`limit` と `offset` の影響を受けない値）が入ります。

* `limit` の既定値: **1000**
* `limit` の最大値: **10000**

**例: 500件ずつ全件を取得する場合**

```
Page 1: GET /export/sessions/summary?limit=500&offset=0    → X-Total-Count: 2450
Page 2: GET /export/sessions/summary?limit=500&offset=500
Page 3: GET /export/sessions/summary?limit=500&offset=1000
Page 4: GET /export/sessions/summary?limit=500&offset=1500
Page 5: GET /export/sessions/summary?limit=500&offset=2000
```

`offset` が `X-Total-Count` 以上になるまで続けます。

{% hint style="success" %}
**補足:** データが同時に変化している場合、`X-Total-Count` はおおよその値になります。件数の集計とデータの取得は別々に実行されるため、その間にセッションが追加・削除されると、わずかにずれることがあります。
{% endhint %}

{% tabs %}
{% tab title="cURL" %}

```bash
# 1ページ目（-D - を付けるとレスポンスヘッダーを表示できます）
curl -D - \
  -H "Authorization: Bearer your-api-key" \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/export/sessions/summary?limit=500&offset=0"

# 2ページ目
curl -H "Authorization: Bearer your-api-key" \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/export/sessions/summary?limit=500&offset=500"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

offset = 0
limit = 500
all_sessions = []

while True:
    response = requests.get(
        f"{BASE_URL}/export/sessions/summary",
        headers=headers,
        params={"limit": limit, "offset": offset}
    )
    data = response.json()
    all_sessions.extend(data["sessions"])

    total = int(response.headers["X-Total-Count"])
    offset += limit
    if offset >= total:
        break

print(f"Fetched {len(all_sessions)} of {total} sessions")
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
let offset = 0;
const limit = 500;
const allSessions = [];

while (true) {
  const response = await fetch(
    `${BASE_URL}/export/sessions/summary?limit=${limit}&offset=${offset}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  allSessions.push(...data.sessions);

  const total = parseInt(response.headers.get('X-Total-Count'));
  offset += limit;
  if (offset >= total) break;
}
```

{% endtab %}
{% endtabs %}

***

## レスポンスヘッダー

エクスポートのレスポンスには、すべて次のヘッダーが付きます。

| ヘッダー                  | 説明                                  | 例                                                         |
| --------------------- | ----------------------------------- | --------------------------------------------------------- |
| `Content-Type`        | 指定した形式に応じた MIME タイプ                 | `application/json`                                        |
| `Content-Disposition` | ダウンロード時のファイル名の候補                    | `attachment; filename="sessions-summary_2026-03-06.json"` |
| `X-Total-Count`       | 条件に合う記録の総数（`limit`・`offset` を適用する前） | `2450`                                                    |

### ファイル名の付け方

```
{data_type}_{date}.{extension}
```

| 要素          | 説明                    | 例                                     |
| ----------- | --------------------- | ------------------------------------- |
| `data_type` | エンドポイントに対応するエクスポートの種類 | `sessions-summary`、`sessions-details` |
| `date`      | 当日の日付（`YYYY-MM-DD`）   | `2026-03-06`                          |
| `extension` | 形式に応じた拡張子             | `json`                                |

{% hint style="success" %}
**ブラウザでダウンロードする場合**\
XHR や fetch で API を呼び出した場合、`Content-Disposition` ヘッダーがあっても自動ではダウンロードされません。クライアント側で、レスポンスの本文からダウンロードを作成する必要があります。このヘッダーは CORS の `Access-Control-Expose-Headers` で公開されているため、スクリプトから読み取れます。
{% endhint %}

***

## エラーレスポンス

エラーは JSON で返り、内容は `message` に入ります。

```json
{ "message": "error description" }
```

ただし、認証エラー（`401`）とレート制限（`429`）は形式が異なり、内容は `message` ではなく `error` に入ります。

```json
{ "error": "Invalid API key for this organization" }
```

| ステータス | 条件                                                                                                                  | メッセージ                                                           |
| ----- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `400` | `format` の値が正しくない                                                                                                   | `unsupported export format`                                     |
| `400` | 詳細のエンドポイントで xAPI を指定した                                                                                              | `xAPI format is only available for the sessions summary export` |
| `400` | `time_from` または `time_to` が正しくない                                                                                    | `invalid time_from: must be RFC 3339 format`                    |
| `400` | `limit` が最大値を超えている                                                                                                  | `limit must be between 1 and 10000`                             |
| `400` | `limit` または `offset` が整数ではない                                                                                        | （記載なし）                                                          |
| `400` | `status` に知らない値が含まれている                                                                                              | `invalid session status filter`                                 |
| `401` | APIキーが無い、形式が正しくない、または URL の組織のものではない                                                                                | （`error` に内容が入ります）                                              |
| `429` | レート制限を超えた。`Retry-After` ヘッダーに再試行までの待ち秒数が入ります。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 | （`error` に内容が入ります）                                              |
| `500` | データベースまたはデータ変換の失敗                                                                                                   | `unable to export data`                                         |

## 関連ページ

* [アナリティクス](https://docs.digitalhumans.jp/itp-guide/analytics.md)
* [受講履歴と結果の見方](https://docs.digitalhumans.jp/itp-guide/take-training/history.md)
* [セキュリティとデータの取り扱い](https://docs.digitalhumans.jp/itp-guide/network-requirements/security-and-data.md)
