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

# オブジェクト指向API

> Olostep APIオブジェクトがどのように連携するかを理解する

OlostepのAPIはオブジェクトを中心に設計されています。この設計を理解することで、より効果的な統合を構築できます。

***

## すべてはオブジェクト

Olostepのすべてのリソースは、ユニークな識別子を持つオブジェクトです。API、SDK、またはダッシュボードを介して作成する場合でも、参照、更新、クエリが可能なオブジェクトが返されます。

| リソース     | オブジェクトID形式   | 例                 |
| -------- | ------------ | ----------------- |
| Scrape   | `scrape_*`   | `scrape_abc123`   |
| Batch    | `batch_*`    | `batch_xyz789`    |
| Crawl    | `crawl_*`    | `crawl_def456`    |
| Map      | `map_*`      | `map_ghi012`      |
| Answer   | `answer_*`   | `answer_jkl345`   |
| Search   | `search_*`   | `search_mno678`   |
| Monitor  | `monitor_*`  | `monitor_mno678`  |
| File     | `file_*`     | `file_mno678`     |
| Schedule | `schedule_*` | `schedule_pqr901` |

***

## オブジェクトにはライフサイクルがある

一部のOlostepオブジェクトは、`status`フィールドを通じて状態を追跡します。この状態機械パターンにより、各リソースがライフサイクルのどこにあるかを正確に知ることができます。

### バッチ

バッチには、**バッチ**自体と個々の**アイテム**の2つのステータスレベルがあります。

**バッチステータス:**

```
in_progress → completed
```

| ステータス         | 説明              |
| ------------- | --------------- |
| `in_progress` | URLがスクレイプされています |
| `completed`   | 処理が完了しました       |

<Note>
  **バッチレベルの失敗は非常に稀です。** バッチはほぼ必ず完了します — 一部のURLが失敗しても、バッチ自体は`completed`ステータスに達します。壊滅的なインフラストラクチャの失敗（例：エンリッチメント中のLLMサービスの停止）の場合にのみ、バッチが失敗することがあります。これはバッチの0.01%未満に影響します。
</Note>

**アイテムステータス:**

バッチ内の各URLは、独自のステータスを持つ個々のアイテムとして追跡されます：

| ステータス     | 説明                |
| --------- | ----------------- |
| `success` | URLが正常にスクレイプされました |
| `failed`  | URLをスクレイプできませんでした |

アイテムが失敗する理由：

* URLがブロックされているかエラーを返す
* パーサーの出力が欠落している
* ネットワーク/フェッチエラー

失敗したアイテムには、失敗を説明する`code`と`message`を含む`error`オブジェクトが含まれます。バッチは依然として完了します — 結果を処理する際に各アイテムのステータスを確認してください。

### クローラー

```
in_progress → completed
```

| ステータス         | 説明                   |
| ------------- | -------------------- |
| `in_progress` | URLを積極的に発見および処理しています |
| `completed`   | クロールが完了しました          |

<Note>
  **クローラーは常に完了します。** たとえクロールが0 URLを発見した場合（robots.txtによるブロックや無効な開始URLのため）、クロールステータスは`completed`になります。結果を確認するには`pages_count`フィールドを確認してください。
</Note>

### モニター

モニターは、ワンショットリソースよりも豊富なライフサイクルを持つ長寿命のオブジェクトです：

```
provisioning → active ⇄ paused
            ↘ failed
```

| ステータス          | 説明                                                   |
| -------------- | ---------------------------------------------------- |
| `provisioning` | エージェント、仕様、プランナー、およびスケジュールが設定されています                   |
| `active`       | スケジュールが有効になり、`schedule.frequency`で実行されます             |
| `paused`       | `POST /v1/monitors/:monitor_id/pause`でスケジュールが無効化されます |
| `failed`       | プロビジョニングまたはスケジュール更新に失敗しました（`error_message`が設定されます）   |
| `deleted`      | `DELETE /v1/monitors/:monitor_id`でソフト削除されます          |

モニターを作成すると、HTTP `202`が`status: provisioning`で返されます。モニターは、計画が追跡対象を解決すると`active`になります — `GET /v1/monitors/:monitor_id`をポーリングするか、`?stream=1`でプロビジョニングイベントをストリーミングします。`active`なモニターのみが一時停止でき、`paused`なモニターのみが再開できます。更新はモニターがまだ`provisioning`中の場合、`409`を返します。

***

## リトリーブパターン

多くのオブジェクトは、後で取得できるコンテンツを生成します。`retrieve_id`パターンを使用すると、再処理せずにコンテンツを取得できます。

```bash theme={null}
# retrieve_idを使用してコンテンツを取得
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
  -H "Authorization: Bearer <your_token>"
```

このパターンは以下で使用されます：

* **バッチアイテム** — 処理された各URLに`retrieve_id`が付与されます
* **クロールページ** — クロールされた各ページに`retrieve_id`が付与されます

`/v1/retrieve`エンドポイントは、返すコンテンツタイプを指定する`formats`パラメータを受け入れます（`html`、`markdown`、`json`、`text`）。

***

## Webhooks: イベント駆動型の更新

状態の変化をポーリングする代わりに、オブジェクトの状態が変化したときにイベントを受け取るように[webhooks](/api-reference/common/webhooks)を設定してください。

```json theme={null}
{
  "event": "batch.completed",
  "data": {
    "id": "batch_xyz789",
    "status": "completed",
    "items_total": 100,
    "items_completed": 100
  }
}
```

***

## メタデータ: あなたのデータを私たちのデータと一緒に

[metadata](/api-reference/common/metadata)を使用して、オブジェクトにカスタムのキーと値のペアを添付します。これにより、Olostepリソースを内部システムにリンクできます。

```json theme={null}
{
  "items": [{"url": "https://example.com"}],
  "metadata": {
    "order_id": "12345",
    "customer": "acme-corp"
  }
}
```

***

## まとめ

| コンセプト        | 説明                           |
| ------------ | ---------------------------- |
| **オブジェクト**   | すべてのリソースにはユニークなIDがあり、クエリ可能です |
| **ライフサイクル**  | `status`フィールドを通じて進行状況を追跡     |
| **リトリーブ**    | `retrieve_id`で後でコンテンツを取得     |
| **Webhooks** | 状態が変化したときに通知を受け取る            |
| **メタデータ**    | 任意のオブジェクトに独自のデータを添付          |