> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # リサーチタスク一覧を取得 > 呼び出し元の API キーについて、ナレッジベースが保持するリサーチタスクを新しい順に一覧表示します。 別のキーで作成されたタスクや、Dify から作成されたタスクは表示されません。 段階や日付によるフィルターはありません。実行中のタスクを追跡するには、[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) の各レスポンスの `id` を保存しておいてください。 計画、作成、ポーリング、結果の読み取りの流れについては、[リサーチタスクの実行](/ja/api-reference/guides/knowledge-base#run-a-research-task) を参照してください。 ## OpenAPI ````yaml /ja/api-reference/openapi_service.json get /knowledge-fs/spaces/{knowledge_base_id}/research-tasks openapi: 3.0.1 info: description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 title: Dify サービス API version: 1.0.0 servers: - description: Dify サービス API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - description: チャットメッセージとインタラクションに関連する操作です。 name: チャットメッセージ - description: ファイルのアップロードとプレビューの操作です。 name: ファイル操作 - description: エンドユーザー情報に関連する操作です。 name: エンドユーザー - description: ユーザーフィードバックの操作です。 name: メッセージフィードバック - description: 会話管理に関連する操作です。 name: 会話管理 - description: テキスト読み上げと音声認識の操作です。 name: 音声・テキスト変換 - description: アプリケーション設定と情報を取得する操作です。 name: アプリケーション設定 - description: ダイレクト返信用のアノテーション管理に関連する操作です。 name: アノテーション管理 - description: 人間の入力を要する一時停止中のワークフローの再開操作です。 name: 人間の入力 - description: ワークフローの実行と管理のための操作です。 name: ワークフロー実行 - description: テキスト生成に関連する操作です。 name: 完了メッセージ - description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 name: ナレッジベース - description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 name: ドキュメント - description: ドキュメントチャンクと子チャンクの管理のための操作です。 name: チャンク - description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 name: メタデータ - description: ナレッジベースタグとタグバインディングの管理のための操作です。 name: タグ管理 - description: 利用可能なモデルを取得するための操作です。 name: モデル - description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 name: ナレッジパイプライン - description: ナレッジベースに質問し、回答をストリーミングで受け取ります。 name: クエリ - description: クエリが何を検索したか、またその理由を確認します。 name: クエリ記録 - description: リサーチの質問をバックグラウンドで実行し、その結果を取得します。 name: リサーチタスク - description: ナレッジベースのドキュメントと、そのファイル、リビジョン、チャンクを読み取り、ドキュメントにメタデータのラベルを付けます。 name: ドキュメントとチャンク - description: インデックス処理の追跡、キャンセル、再試行と、ナレッジベースのバックグラウンドタスクの一覧表示を行います。 name: インデックスタスク - description: ドキュメントファイル、ファイルのバッチ、またはソースの削除を、完了するまで追跡します。 name: 削除ジョブ - description: ナレッジベースにデータを供給するソース、その同期スケジュール、接続を管理します。 name: ソース - description: ソースの即時同期、ウェブサイトのページまたはプロバイダーのアイテムのインポート、実行の追跡、キャンセル、再試行を行います。 name: ソースの同期とインポート - description: ナレッジベースのモデルと検索設定の読み取りと変更、および変更によって始まる移行の追跡を行います。 name: 設定 paths: /knowledge-fs/spaces/{knowledge_base_id}/research-tasks: get: tags: - Research Tasks summary: リサーチタスク一覧を取得 description: >- 呼び出し元の API キーについて、ナレッジベースが保持するリサーチタスクを新しい順に一覧表示します。 別のキーで作成されたタスクや、Dify から作成されたタスクは表示されません。 段階や日付によるフィルターはありません。実行中のタスクを追跡するには、[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) の各レスポンスの `id` を保存しておいてください。 計画、作成、ポーリング、結果の読み取りの流れについては、[リサーチタスクの実行](/ja/api-reference/guides/knowledge-base#run-a-research-task) を参照してください。 operationId: listResearchTasks parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: 前のページの `next_cursor` から取得したカーソルです。 in: query name: cursor required: false schema: maxLength: 1000 minLength: 1 type: string - description: 1 ページあたりのタスク数です。 in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: success: summary: レスポンス例 value: data: - budget_usd: 1.5 completed_at: 1788681642000 cost: budgetUsd: 1.5 entries: - costUsd: 0.0011 provider: openai recordedAt: 1788681603000 step: research.plan usage: completionTokens: 58 estimated: false promptTokens: 310 researchModelCallId: attempt:1:call-1 reserved: false status: succeeded totalTokens: 368 - costUsd: 0.0124 provider: openai recordedAt: 1788681641000 step: query.answer usage: completionTokens: 412 estimated: false promptTokens: 3180 researchModelCallId: attempt:1:call-2 reserved: false status: succeeded totalTokens: 3592 totalUsd: 0.0135 created_at: 1788681600000 error: null failure: null id: e4d1b7a2-3c5f-4d8e-9a0b-1c2d3e4f5a6b knowledge_space_id: b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d limits: max_retrieval_steps: 8 max_scanned_resources: 800 max_tool_calls: 12 timeout_ms: 120000 metadata: client_request_id: client-20260907-0001 ticket: SUP-1042 mode: research query: >- What changed in the 2025 refund policy, and which regions are affected? stage: completed top_k: 10 updated_at: 1788681642000 - budget_usd: null completed_at: 1788678090000 cost: entries: - costUsd: 0.0009 provider: openai recordedAt: 1788678003000 step: graph.plan usage: completionTokens: 44 estimated: false promptTokens: 260 researchModelCallId: attempt:1:call-3 reserved: false status: succeeded totalTokens: 304 totalUsd: 0.0009 created_at: 1788678000000 error: RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED failure: action: retry category: dependency code: RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED message: >- A service required by Agent Knowledge Base is temporarily unavailable. parameters: null retryPolicy: manual stage: research traceId: 0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d id: 0a9b8c7d-6e5f-4a4b-9c3d-2e1f0a9b8c7d knowledge_space_id: b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d limits: null metadata: {} mode: deep query: Which suppliers are named in the 2024 audit findings? stage: failed top_k: 10 updated_at: 1788678090000 next_cursor: null schema: properties: data: description: >- リサーチタスクです。新しい順に並びます。各項目は [リサーチタスクを取得](/ja/api-reference/research-tasks/get-research-task) と同じオブジェクトです。回答は含まれません。 items: $ref: '#/components/schemas/KnowledgeBaseResearchTask' type: array next_cursor: description: 次のページのカーソルです。最後のページでは `null` です。`cursor` として送り返してください。 nullable: true type: string type: object description: 1 ページ分のリサーチタスクです。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request (validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limit type: less_than_equal description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。 - `knowledge_fs_invalid_request`：`cursor` がこの操作で発行された値ではないか、クエリ文字列にこの操作が受け付けないパラメータが含まれています。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：`Authorization` ヘッダーがないか、キーが不明であるか、ナレッジベースの API キーではありません。 - `knowledge_fs_invalid_credential`：キーは有効ですが、キーのワークスペースにこの ID のナレッジベースが存在しないか、キーがワークスペースに紐付いていません。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `forbidden`：Dify Cloud で、ワークスペースがサブスクリプションで定められたナレッジベースのリクエストレート制限に達しました。読み取りを含め、すべての呼び出しがカウントされます。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: |- - `knowledge_fs_resource_not_found`：ナレッジベース ID が認識されません。 - `not_found`：このデプロイ環境では Agent ナレッジベース機能が無効になっています。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_2: summary: knowledge_fs_upstream_unavailable (without error details) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：時間内に応答が返らなかったか、応答を読み取れませんでした。しばらく待ってから再試行してください。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：このワークスペースで Agent ナレッジベース機能が設定されていないか、このデプロイ環境ではこの操作を利用できません。または、リクエストの認可中に、このナレッジベースに対するキーのアクセス権が変更されました。 - `knowledge_fs_operation_unavailable`：現在このリクエストを処理できません。`failure.retryPolicy` に従ってください。 components: schemas: KnowledgeBaseResearchTask: properties: budget_usd: description: リクエストで指定された支出上限（USD）です。設定されていない場合は `null` です。 nullable: true type: number completed_at: description: >- タスクが `completed`、`failed`、`canceled` のいずれかに達した日時（エポックミリ秒）です。タスクの実行中は `null` です。 nullable: true type: number cost: description: これまでに記録された支出です。 properties: budgetExceeded: description: >- 支出が `budgetUsd` を超え、それを理由にタスクがキャンセルされた場合は `true` です。それ以外の場合は含まれません。 type: boolean budgetUsd: description: リクエストの `budgetUsd` です。予算が設定されていない場合は含まれません。 type: number entries: description: 記録されたモデル呼び出しごとに 1 つのエントリが入り、古い順に並びます。 items: properties: costUsd: description: 呼び出しのコスト（USD）です。 type: number provider: description: 呼び出しを処理したモデルプロバイダーです。 type: string recordedAt: description: コストが記録された日時（エポックミリ秒）です。 type: number step: description: >- 呼び出しを行ったステップで、`pageindex.layer`、`pageindex.semantic`、`pageindex.whole-tree`、`research.judge`、`research.plan`、`graph.plan`、`query.answer`、`query.image-expand` のいずれかです。 type: string usage: description: >- 呼び出しのトークン使用量です。`promptTokens`、`completionTokens`、`totalTokens`、`estimated`、`reserved`、`status`（`reserved`、`succeeded`、`failed` のいずれか）、`researchModelCallId` を含みます。実行中の呼び出しの予約もエントリとして記録され、`totalUsd` に計上されます。 type: object type: object type: array totalUsd: description: '`entries[].costUsd` の合計（USD）です。最初のモデル呼び出しが記録されるまでは `0` です。' type: number type: object created_at: description: タスクの作成日時（エポックミリ秒）です。 type: number error: description: >- 失敗コードで、`failure.code` と同じ値です。`stage` が `failed` の場合にのみ設定され、それ以外の場合は、キャンセルされたタスクも含めて `null` です。 失敗したリサーチタスクでは、`failure.code` は `RESEARCH_TASK_CAPABILITY_REVOKED`、`RESEARCH_TASK_DISPATCH_DEAD`、`RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED`、`RESEARCH_TASK_FAILED`、`RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID`、`RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID` のいずれかです。 nullable: true type: string failure: description: >- エラー詳細です。`stage` が `failed` の場合にのみ設定され、それ以外の場合は `null` です。ここでは、値のないメンバーは `null` になります。`traceId` はタスク ID です。 `action` が `retry` の場合は、[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) で新しいタスクを作成してください。 nullable: true properties: action: description: >- 推奨される次の対応です。ある場合は `configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload`、`retry` のいずれかです。該当しない場合は `null` です。 nullable: true type: string category: description: >- 失敗の種類で、`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout`、`validation` のいずれかです。 type: string code: description: リサーチタスクの失敗コードで、このタスクの `error` と一致します。 type: string message: description: タスクの失敗に対する公開用メッセージです。プロバイダーのエラー詳細は公開されません。 type: string parameters: additionalProperties: true description: >- 失敗の内容を補足する最大 8 個の値です。キーは `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds`、`status` のいずれかです。値がない場合は `null` です。 nullable: true type: object retryPolicy: description: >- 再試行で解決できるかどうかです。`automatic`（サービスが自動で再試行）、`manual`（呼び出し側で再試行）、`after_configuration`（先に Dify でナレッジベースの設定を修正）、`never`（リクエストを変更）のいずれかです。 type: string stage: description: 常に `research` です。 nullable: true type: string traceId: description: リサーチタスク ID です。管理者に問い合わせる際に伝えてください。 nullable: true type: string type: object id: description: リサーチタスク ID です。タスクに対する各操作で `research_task_id` として使用します。 type: string knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string limits: description: >- リクエストで指定された制限で、キーはスネークケースです。リクエストに `limits` が含まれていなかった場合は `null` です。送信されなかったメンバーは `null` になります。[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) に再度送信する前に、キーをキャメルケースに戻してください。 nullable: true properties: max_retrieval_steps: description: リクエストの `limits.maxRetrievalSteps` の値です。 nullable: true type: integer max_scanned_resources: description: リクエストの `limits.maxScannedResources` の値です。 nullable: true type: integer max_tool_calls: description: リクエストの `limits.maxToolCalls` の値です。 nullable: true type: integer timeout_ms: description: リクエストの `limits.timeoutMs` の値です。 nullable: true type: integer type: object metadata: description: 作成時に送信された `metadata` オブジェクトです。`__knowledgeFs` で始まるキーは除かれます。 type: object mode: description: タスクの検索の深度で、`fast`、`deep`、`research` のいずれかです。 nullable: true type: string query: description: 保存されたとおりのリサーチの質問です。 type: string query_images: description: 元のクエリで使用された画像です。テキストのみのクエリでは省略されます。 items: properties: byte_size: description: この API では常に `null` です。 minimum: 0 nullable: true type: integer mime_type: description: この API では常に `null` です。 nullable: true type: string name: description: この API では常に `null` です。 nullable: true type: string preview_url: description: この API では常に `null` です。 nullable: true type: string upload_file_id: description: 元のクエリで使用された画像ファイルの ID です。 type: string required: - upload_file_id type: object type: array stage: description: >- ライフサイクル上でのタスクの現在位置です。タスクは 1 段階ずつ進みます： - `queued`：受け付け済みで、ワーカーを待っています。 - `planning`：検索計画を決定しています。 - `retrieving`：ナレッジベースを検索しています。検索のチェックポイントが書き込まれることがあります。 - `analyzing`：検索されたチャンクを読み、評価しています。 - `generating`：回答を作成しています。最終結果はこの段階で書き込まれます。 - `completed`：完了しました。結果は [リサーチタスクの結果一覧を取得](/ja/api-reference/research-tasks/list-research-task-results) で取得します。 - `failed`：エラーで停止しました。`error` と `failure` を参照してください。 - `canceled`：[リサーチタスクをキャンセル](/ja/api-reference/research-tasks/cancel-research-task) または予算によって停止しました。 - `paused`：タスクは一時停止中です。失敗の詳細をデプロイ環境の運用担当者に確認するか、タスクをキャンセルしてください。 `completed`、`failed`、`canceled` は最終状態です。 type: string top_k: description: >- 検索結果をマージしてリランクした後に残すチャンクの最大数です。リクエストの `topK`、または省略時はナレッジベースの **トップ K** の値です。 nullable: true type: integer updated_at: description: タスクレコードの最終更新日時（エポックミリ秒）です。内部のチェックポイントや再試行のスケジュール設定による更新も含みます。 type: number type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.