WebExtrator タスククエリ API 統合ガイド

POST https://api.acedata.cloud/webextrator/tasks WebExtrator タスククエリ API は、過去の render / extract タスク結果を照会するために使用されます。一般的な使用法：

非同期タスク完了後に再照会して完全なエンベロープを取得（callback_url プッシュまたは手動ポーリングを除く）。
監査自分が提出した内容を確認する —— タスク記録は元の request と最終 response を同時に保存します。
バッチ回填 —— 一度に id または trace_id で複数のレコードを取得。

タスク記録は Redis に 7 日間保持されます。タスククエリインターフェースは無料（クレジット使用量にはカウントされません）。

認証

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

自分の AceDataCloud アカウント下のタスクのみを照会できます。

リクエストパラメータ

リクエストボディは action によって区別される判別式の組み合わせで、2 つのアクションがあります：

`action: "retrieve"` —— 単一照会

フィールド	タイプ	必須	説明
`action`	const	✅	固定 `"retrieve"`。
`id`	string	二者択一	タスク ID（各 render/extract エンベロープの `task_id` フィールドに表示されます）。
`trace_id`	string	二者択一	呼び出しチェーン ID（エンベロープの `trace_id` フィールド）。

id と trace_id は二者択一で渡します。

`action: "retrieve_batch"` —— バッチ照会

フィールド	タイプ	必須	説明
`action`	const	✅	固定 `"retrieve_batch"`。
`ids`	string[]	二者択一	タスク ID リスト。
`trace_ids`	string[]	二者択一	呼び出しチェーン ID リスト。
`offset`	number	❌	ページオフセット（デフォルト 0）。
`limit`	number	❌	単ページサイズ、1–100（デフォルト 50）。

ids と trace_ids は二者択一で渡します。

単一レスポンス

{
  "task": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "trace_id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "extract",
    "created_at": 1777717800.05,
    "started_at": 1777717800.123,
    "finished_at": 1777717802.535,
    "elapsed": 2.412,
    "request": {
      "url": "https://en.wikipedia.org/wiki/Diffbot",
      "expected_type": "article"
    },
    "response": {
      "success": true,
      "data": { /* 完全な extract エンベロープ */ }
    }
  }
}

見つからない場合は { "task": null } を返します（HTTP 200、404 ではありません）。 task オブジェクトのタイミングフィールドの説明は以下の通りです。

created_at、タスク作成時間、Unix タイムスタンプ（秒、浮動小数点）。
started_at、タスク開始実行時間、Unix タイムスタンプ（秒、浮動小数点）。タスクがまだ開始されていない場合は null。
finished_at、タスク完了時間、Unix タイムスタンプ（秒、浮動小数点）。タスクが未完了の場合は null。
elapsed、タスク実行にかかった時間、単位は秒（浮動小数点、3 桁の小数点以下を保持）。タスクが未完了の場合は null。

バッチレスポンス

{
  "tasks": [
    { /* 単一の .task 構造と同じ */ },
    { /* ... */ }
  ],
  "offset": 0,
  "limit":  50
}

存在しない ID はエラーにならず、単に tasks から欠落します。

例

task_id による単一照会

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }'

trace_id による単一照会

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve",
    "trace_id": "550e8400-e29b-41d4-a716-446655440001"
  }'

バッチ照会

curl -X POST https://api.acedata.cloud/webextrator/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "retrieve_batch",
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "limit": 50
  }'

Python (requests) —— 完了するまでポーリング

import os, time, requests

API_KEY = os.environ["ACEDATA_API_KEY"]
BASE = "https://api.acedata.cloud"

# 1) 非同期抽出を提出
queue = requests.post(
    f"{BASE}/webextrator/extract",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"url": "https://example.com", "mode": "async"},
).json()

job_id = queue["jobId"]

# 2) タスク API を使用してタスクが完了するまでポーリング
while True:
    r = requests.post(
        f"{BASE}/webextrator/tasks",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={"action": "retrieve", "id": job_id},
    ).json()
    task = r.get("task")
    if task and task.get("finished_at"):
        print("経過時間", task["elapsed"], "秒")
        print(task["response"]["data"]["title"])
        break
    time.sleep(2)

Node.js (fetch) —— コールバックを受け取った後に完全なエンベロープを取得

// あなたの callback_url 処理関数内で：
app.post('/hooks/webextrator', async (req, res) => {
  res.status(200).end();              // 先に迅速に ack

  const taskId = req.body?.task_id;
  if (!taskId) return;

  const fetchRes = await fetch('https://api.acedata.cloud/webextrator/tasks', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ACEDATA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ action: 'retrieve', id: taskId }),
  });
  const { task } = await fetchRes.json();
  console.log('完全なエンベロープ:', task.response.data);
});

エラーレスポンス

HTTP	`error.code`	意味
400	`bad_request`	検証失敗（`action` が欠如、`id` と `trace_id` を同時に送信など）。
401	`unauthorized`	欠如または無効な `Authorization: Bearer …`。

{ "error": { "code": "bad_request", "message": "..." } }

ヒントと落とし穴

trace_id をカスタマイズ可能であればカスタマイズしてください。 原始の render/extract リクエストで ?trace_id=…（クエリストリング）をアップロードし、それを自分のビジネス ID（ワークフローの run id など）に合わせてください。そうすれば、ビジネス ID でタスクを検索できます。送信しなかった場合、サーバーは自動的に UUID を生成します。
保持期間は 7 日です。 それ以前のタスクは task: null を返します —— 長期的なアーカイブが必要な場合は、自分でデータベースに保存してください。
タスクのクエリは無料です。 何回でも調べたいだけ調べてください。原始の render/extract 呼び出し時に費用はすでに支払われています。
非同期 + コールバックを優先し、ポーリングではなく。 ビジネスが許可する場合、元のリクエストに callback_url を渡し、プラットフォームがエンベロープをあなたにプッシュするようにしてください。2 秒ごとにポーリングするよりも効率的です。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

プロキシ

上級

WebExtrator タスククエリ API 統合ガイド

認証

リクエストパラメータ

`action: "retrieve"` —— 単一照会

`action: "retrieve_batch"` —— バッチ照会

単一レスポンス

バッチレスポンス

例

task_id による単一照会

trace_id による単一照会

バッチ照会

Python (requests) —— 完了するまでポーリング

Node.js (fetch) —— コールバックを受け取った後に完全なエンベロープを取得

エラーレスポンス

ヒントと落とし穴

​認証

​リクエストパラメータ

​action: "retrieve" —— 単一照会

​action: "retrieve_batch" —— バッチ照会

​単一レスポンス

​バッチレスポンス

​例

​task_id による単一照会

​trace_id による単一照会

​バッチ照会

​Python (requests) —— 完了するまでポーリング

​Node.js (fetch) —— コールバックを受け取った後に完全なエンベロープを取得

​エラーレスポンス

​ヒントと落とし穴

認証

リクエストパラメータ

`action: "retrieve"` —— 単一照会

`action: "retrieve_batch"` —— バッチ照会

単一レスポンス

バッチレスポンス

例

task_id による単一照会

trace_id による単一照会

バッチ照会

Python (requests) —— 完了するまでポーリング

Node.js (fetch) —— コールバックを受け取った後に完全なエンベロープを取得

エラーレスポンス

ヒントと落とし穴