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

# セッション

> セッションのライフサイクル、ステータス遷移、発行されるイベント。

**セッション**は、1回のAI面接（会話、録音、トランスクリプト、スコアカード）を
表します。セッションは利用の中核となる単位であり、APIで最も多く扱われる
オブジェクトです。

## ステータスのライフサイクル

```text theme={null}
   created       ┌──────────────┐
   ─────────────►│  scheduled   │  Session row created. AI is provisioned;
                 └─────┬────────┘  candidate has a join URL.
                       │
        candidate joins│
                       ▼
                 ┌──────────────┐  AI is conversing with the candidate.
                 │ in_progress  │  Transcript streams in; authenticity
                 └─────┬────────┘  signals captured live.
                       │
                       │
       ┌───────────────┼───────────────┐
       │               │               │
  hangs up early   completes   recruiter cancels
       ▼               ▼               ▼
 ┌──────────┐   ┌──────────┐    ┌──────────┐
 │  failed  │   │ completed│    │cancelled │
 └──────────┘   └──────────┘    └──────────┘
```

<ResponseField name="scheduled">
  セッション行が作成された状態。AIはまだ参加していません。候補者は招待に
  含まれる `join_url` からいつでも参加できます。
</ResponseField>

<ResponseField name="in_progress">
  候補者が参加し、AIが面接を実施中。トランスクリプトと真正性シグナルが
  セッションレコードにライブでストリーミングされます。
</ResponseField>

<ResponseField name="completed">
  面接が自然に終了した状態。AIが締めの言葉を述べて通話を終了しました。
  スコアカードは2分以内に準備されます。
</ResponseField>

<ResponseField name="failed">
  候補者が面接の途中で切断したか、技術的な障害がセッションを中断しました。
  部分的なトランスクリプトは利用できる場合がありますが、スコアカードはありません。
</ResponseField>

<ResponseField name="cancelled">
  候補者が参加する前に、リクルーターがAPIまたはUIからセッションを
  キャンセルしました。面接は実施されていません。
</ResponseField>

## ステータスの変更はイベントを発行する

すべての状態遷移はWebhookを発火させます。それらを受信するように
エンドポイントを設定してください。ペイロードの形状とHMAC署名については
[Webhook](/jp/concepts/webhooks)を参照してください。

| 遷移             | 発火するイベント                                     |
| -------------- | -------------------------------------------- |
| 作成（APIまたはUI経由） | `session.created`                            |
| 候補者が参加         | `session.started`                            |
| 自然に完了          | `session.completed`                          |
| 失敗／切断          | `session.failed`                             |
| リクルーターがキャンセル   | `session.cancelled`                          |
| スコアカードが確定      | `session.scored` *（`completed` の30秒〜2分後に発火）* |

<Tip>
  完全なルーブリックのスコアカードが必要な場合は、`session.completed` では
  なく `session.scored` をリッスンしてください。`session.completed` はAIが
  通話を終了した瞬間に発火します。採点は非同期で行われ、`session.scored` が
  スコアカードが確定したことを示すシグナルです。
</Tip>

## セッションの読み取り

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.intervyo.ai/api/v1/sessions/e3a1c2d4-..." \
    -H "x-api-key: $INTERVYO_API_KEY"
  ```

  ```ts TypeScript theme={null}
  const res = await fetch(
    `https://www.intervyo.ai/api/v1/sessions/${id}`,
    { headers: { "x-api-key": process.env.INTERVYO_API_KEY! } },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.get(
      f"https://www.intervyo.ai/api/v1/sessions/{session_id}",
      headers={"x-api-key": os.environ["INTERVYO_API_KEY"]},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

返り値:

```json theme={null}
{
  "data": {
    "id": "e3a1c2d4-...",
    "status": "completed",
    "role_id": "ce1cd564-...",
    "candidate_id": "ba4f2cdd-...",
    "stage": "screen",
    "score": "8.2",
    "passed": true,
    "recommendation": "hire",
    "ai_feedback": "Strong candidate with clear system design...",
    "evaluation_breakdown": [
      { "name": "Technical Depth", "score": 8.5, "feedback": "..." },
      { "name": "Communication",   "score": 7.8, "feedback": "..." }
    ],
    "duration_seconds": 2740,
    "started_at": "2026-06-02T07:48:31Z",
    "ended_at": "2026-06-02T08:21:14Z"
  }
}
```

完全なスキーマについては[セッションの取得](/api-reference/sessions/get-sessions-id)を参照してください。

## 再実施とリトライ

各セッションは終了状態（`completed` / `failed` / `cancelled`）になると
変更不可になります。同じ候補者に対して別の面接が必要な場合、たとえば
技術的な障害の後などには、新しいセッションを作成します。同じ
`(participant, stage)` のセッションは独立した行であり、プラットフォームが
それらを「マージ」したり「上書き」したりすることはありません。

各テンプレートの詳細ページにある応募パネルは、まとめられたステータスを
表示する際に、ステージごとに**最新の**セッションを自動的に選択するため、
リトライは即座に反映されます。

## 複数ステージの進行

複数ステージのテンプレートでは、候補者がステージに合格すると、次の
ステージ用の新しいセッションが自動的に作成されます。これを手動で呼び出す
必要はありません。セッションステータスのミラートリガーが処理します。

3ラウンドのロールを通過する候補者の全体の経路は、最終的に3つの
セッションとなり、ラウンドごとに1つずつ、同じ `candidate_id` を通じて
リンクされます。ラウンドがどのように連鎖するかについては
[ロール](/jp/concepts/roles)を参照してください。

## セッションと応募の違い

これらは混同しやすい2つの異なるオブジェクトです。

| オブジェクト                          | 目的                                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| **セッション**                       | AIと参加者の間の1回の会話。トランスクリプト、スコア、録音を保持します。                                                    |
| **応募**（`template_applications`） | 参加者とテンプレートの関係。人事の承認、スケジュールのステータス、最新のセッションを追跡します。公開の応募フロー、または参加者を手動でテンプレートに追加することで作成されます。 |

テンプレート詳細ページの応募パネルは `template_applications` から読み取り
ますが、表示されるデータ（スコア、トランスクリプト、ステータス）は、
応募に結合された最新のセッションから取得されます。これらは1対Nで対応
しており、1つの応募が時間の経過とともに多数のセッション（リトライ、
複数ステージの進行）を持つことがあります。