アンケート

対象を選び、質問への反応の分布を調べる（合成人格パネル）。

どんな仕事に使うか

• 商品・制度の案に対する反応の分かれ方を、早い段階で眺める
• 設問の言い回しで回答が変わりそうかを試す（品質の注意を見る）
• 自由回答から、論点と対立軸の候補を集める

向かない使い方

• 実在する人々の世論・市場の実数として示すこと（合成人格による回答シミュレーションです）
• クローンの回答を本人の証言として示すこと

入力

出力

結果は GET /api/v1/jobs/{job_id}/result で取れます（要約と値の照合には format=report、原文・全個票の確認には format=json。ほかに md・csv）。CSV を Excel で開くとき：

Excel で CSV をそのまま開くと、式として実行されるセルはありません（' を付けた値は、' つきの文字として表示されます）。ただし、先頭がゼロの数字（例 00123）や日付に見える値（例 2026-10-03・1/2）は、Excel が数値・日付に変えて表示します（ファイルの中は元の文字のままです）。文字のまま読むには、Excel の「データ」→「テキストまたは CSV から」で、データ型の検出を「データ型を検出しない」にして読み込んでください。古い「テキスト ファイル ウィザード」では、セルの中の改行で行が分かれます。

実行の流れ

（任意の見積り：対象の確定・費用の上限・時間 →）受付（job_id がすぐ返る）→ 進捗（retry_after_seconds の目安、または Prefer: wait=30）→ 結果。取消は POST /api/v1/jobs/{id}/cancel（実行中の 1 単位が終わった時点で止まり、そこまでの結果を取得できます）。

• 見積りは、受付の前に該当数・費用の上限・所要時間を知りたいときだけ使います。見積りの preview_id で受け付けるときは、本文を {"preview_id":"pv_…","cost_requirement":{…}} だけにして（cost_requirement は見積りで付けていても受付の本文に書く）、その本文のための新しい Idempotency-Key で送ります（preview_id は 15 分で切れます。くわしくはアンケート）。見積り（POST /api/v1/surveys/preview）はジョブを作らず、preview_id を返すだけです。応答を失ったとき、その見積りを取り出す手段はありません。必要なら、1 日の見積りの回数（仮登録 10 回・確認済み 60 回）をもう 1 回使い、対象の説明文（target.description）があれば対象の変換の費用がもう一度かかることを承知で、見積りし直します。見積りが要らなければ、元の本文（preview_id ではなく依頼の本文）で受付できます。
• 見積りの preview_id は expires_at（15 分後）まで使えます。受付に使うと消えます（もう一度使うと 410 preview_expired。同じ Idempotency-Key・同じ本文の再送は 200 で最初のジョブを返します）。preview_id での受付の本文は {"preview_id":"pv_…","cost_requirement":{…}} だけです（cost_requirement は必須で、見積りのときの値では補いません。ほかの欄を付けると 400）。
• 完全非公開（sealed）の見積りは preview_id が null です。受付は依頼の本文をすべて送ります。
• 待ち方：GET /api/v1/jobs/{id} は、Prefer が無ければ待たずにすぐ返します。Prefer: wait=N（1〜30。30 より大きい値は 30）なら N 秒まで待ち、終わればすぐ返します。終わっていなければ retry_after_seconds（queued は 10、running と canceling は 5）の後にもう一度。どちらの呼び出しも 1 分あたりの枠を 1 回使います。
• 状態：途中は queued・running・canceling、終わった状態は succeeded・partially_succeeded・failed・canceled・expired です。内容を捨てたジョブ（保存期限の後・削除の後・完全非公開の中断）は expired（content_deleted: true）と表示します。
• 結果（GET /api/v1/jobs/{id}/result）：succeeded・partially_succeeded・canceled（実行されなかった回答者は not_executed）・failed（成立した回答が 0 件の結果）は 200（failed・canceled で、閉じる前に入力が保存期限で消えていたときは 410）、途中は 409 result_not_ready（Retry-After: 5）、expired は 410 result_expired です。partial_result_available は、partially_succeeded と canceled で、結果を取れるときに true です（閉じる前に入力が保存期限で消えていた取消は false で、結果は 410）。
• 実行の期限は、実行が始まってから 15 分です（見積りの期限とは別。過ぎると止めて stop_reason が deadline_exceeded）。
• ジョブの途中で止めた理由は状態の stop_reason（deadline_exceeded・budget_exhausted・service_paused・service_tier_mismatch・provider_unavailable。budget_exhausted は費用の上限に達したとき。provider_unavailable は型にある値で、いまの実行係は付けません。提供会社が応答しないときは error の provider_unavailable で知らせます）、失敗の理由は error に入ります（HTTP のエラーとは別の欄です）。

見積り（POST /api/v1/surveys/preview）はジョブを作りませんが、副作用があります：見積りの回数を 1 回使う／対象条件の自然文（target.description）の解釈では、その文を外部の処理先（回答の AI の提供会社）へ送り、運営の API 費用がかかる／見積りの記録と解釈の使い回しを保存する（完全非公開を除く）。LLM を使わない（外部へ送らない）見積りは、target.description を省く・空・全体を指す語（全員・全体・すべて・全て・全部・全パネル・指定なし・条件なし・all・everyone・everybody・日本人・日本人全員・日本在住・日本在住者・日本在住の全員・国内在住・国内在住者）だけのときです。外部への送信を許さない依頼主のもとでは、この経路で見積るか、見積らずに止まってください。実際に起きたことは応答の side_effects に返します。

断られやすい設問（422）

設問の検査は決まった規則（正規表現）で行います。日本語の文を前提にしています。

対象の条件（目録）

対象は自然文（target.description）で書く。API は条件の並びを直に受けない。サーバーが下の目録の属性・演算に分解し、決まったルールで選ぶ（AI はどの人を残すかを決めない）。属性・演算・代理の式・語の決まりは GET /api/v1/populations の target_catalog にあります（filterable_attributes は旧い一覧で、対象の判定には使いません）。年齢は依頼を受けた日（日本時間）の満年齢で判定する（年代別の内訳と抽出は年代の帯のまま）。値が書かれていない・決められない人は選ばない。見積り・受付・結果に「不明で外した数」を出す。

目録で表せない限定（相手・回数・時点や変化・属性をまたぐ「または」・いまの状態か過去の出来事か決まらない語など）は 422 target_unsupported_criterion。details.unsupported_terms に表せない語、details.suggestions に送り直せる言い方を返す。条件を削らない・広げない・近い属性に置き換えない。例：「子持ちの女性」「既婚者」は依頼できます。「親を介護している人」は介護の相手を目録で表せないので 422 になり、「介護している人」と言い換えれば依頼できます。

言語

言語の制限はありません。ただし、パネル・回答の AI への指示・結果の固定の文（注意書き・限界・品質の注記・Markdown と CSV の見出し・stop_reason.message）は日本語です。設問の検査（命令文の除去・事実の設問・二重の問い）は日本語の文を前提にしているため、英語の設問はこれらの検査に当たりません。自由回答の本文と総評は回答の AI が書き、多くは日本語です。エラーは message（日本語）と message_en を返します。日本語で書くことを勧めます。

制限と注意

API の呼び出しの枠は、キーごとと運営主体ごとの両方で数えます（同じ運営主体のキーは枠を共有し、キーを増やしても枠は増えません）。運営主体の管理の口の枠も、運営主体ごとに数えます。 「上限なし」の項目は、上限を置いていません（API の limits・見積りの free_quota では null）。

断られたときの区分（主体の枠と全体の運営枠。型は従来のまま。機械が読める形は GET /api/v1/capabilities の rejection_types）：

所要時間の目安は、見積りの estimate.duration_seconds（下限と上限）で確かめてください。実行の期限は、実行が始まってから 15 分です。