Lists / Research / Credits

このページは保存面の CLI reference です。workflow 手順は Sales List Prep と List Workspace Loop を見てください。

保存面の成果物は row / column / evidence / run / credit です。estimate と candidates は無料の確認、materialize は saved List 作成、enrich は追加 column / evidence 作成です。

operation ごとの無料 / 有料境界は Credit Schedule を正本にします。

正規 sequence

sf list plan "上場企業のうち、売上100億以上" --json
sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "売上100億以上の上場企業" --execute --max-credits 100 --json
sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits 100 --json
sf list export <listId> --format csv --output ./exports/list.csv --json

credit boundary:

• list plan: credit を消費しない
• list estimate: credit を消費しない
• list candidates: credit を消費しない。preview は export できない
• list materialize: Basic credit を使う
• list enrich --estimate: credit を消費しない
• list enrich --execute: found row だけ enrichment credit を使う
• list export: saved List の export は credit を消費しない

sf list plan

自然文を supported / weak / unsupported condition に分解します。

sf list plan "上場企業で売上100億以上、生成AIに関連" --json

確認する key:

• plan.status
• plan.confidence
• plan.supported_conditions[]
• plan.weak_conditions[]
• plan.unsupported_conditions[]
• suggested_next_commands[]

plan.status が needs_human の場合は、estimate に進みません。未対応条件を人間に返し、対応済み条件へ分解します。

sf list estimate

保存前に件数と必要 credit を見ます。

sf list estimate "上場企業のうち、売上100億以上" --json
sf list estimate "上場企業" --industry-33-code 7050,7100 --json

確認する key:

• estimate.estimate_id
• resolved_definition
• resolved_definition.warnings[]
• counts.matched_companies
• billing.materialize.estimated_credits
• unsupported_conditions
• weak_conditions

現行の list estimate は、上場状態、market segment、JPX 33 業種コード、社名/識別子、EDINET 財務指標しきい値、EDINET 本文の bounded search に向いています。

sf list candidates

frozen estimate から薄い preview を見ます。

sf list candidates --from-estimate <estimateId> --json

確認する key:

• estimate_id
• estimate.estimate_id
• companies[].company_id_hint
• companies[].company_hint
• companies[].reason
• meta.candidate_preview_only
• meta.exportable

preview は保存済み List ではありません。CSV が必要なら materialize してから export します。

sf list materialize

estimate を saved List に固定します。

sf list materialize \
  --from-estimate <estimateId> \
  --name "売上100億以上の上場企業" \
  --execute \
  --max-credits 100 \
  --json

確認する key:

• list.list_id
• list.name
• list.row_count
• list.status
• billing.credits_used
• billing.max_credits
• suggested_next_commands[]

--execute と --max-credits は必須です。billing.materialize.estimated_credits が上限を超える場合は、query を絞るか上限を明示的に上げます。

sf list enrich

保存済み List に website enrichment または bounded external enrichment を足します。

sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits 100 --json
sf list enrich <listId> --source parallel --estimate --limit 10 --json
sf list enrich <listId> --source parallel --execute --limit 10 --max-credits 10 --json

確認する key:

• estimate.estimated_max_credits
• estimate.already_completed_companies
• estimate.reusable_existing_companies
• preview_rows[]
• run.run_id
• run.found_count
• run.not_found_count
• run.no_data_count
• billing.credits_used

既存 enrichment が再利用できる場合は、再実行しない理由を説明します。not_found / no_data は課金対象ではありません。

parallel は saved List に絞った後の bounded enrichment です。broad search や会社 universe discovery の入口にしません。

sf list export

保存済み List を CSV に出します。

sf list export <listId> --format csv --output ./exports/list.csv --json

確認する key:

• path
• row_count
• sha256
• expires_at

preview しかない場合は preview_export_not_allowed になります。sf list materialize からやり直してください。

保存済み List の確認

sf list ls --json
sf list ls --status active --refresh-cadence weekly --limit 20 --json
sf list show <listId> --json
sf list preview <listId> --json

確認する key:

• lists[].list_id
• lists[].name
• lists[].status
• list.list_id
• list.row_count
• rows[]
• companies[]
• meta.returned_rows

sf list preview は saved List row の確認に rows[] を返します。companies[] は互換 alias です。sf list publish、sf list refresh、sf list diff は saved List の snapshot / refresh / review surface です。sf list create "AI Targets" --json や sf list create --company-id <id> は、空 List または確認済み company の明示保存に使います。新しい会社群の作成は、通常 plan -> estimate -> candidates -> materialize を使います。

External research

sf research は external research item を canonical observation と分けて保存する面です。

sf research ls --company-id jpx_7203 --json
sf research add jpx_7203 \
  --title "IR note" \
  --content-file ./note.md \
  --json

確認する key:

• items[].research_item_id
• items[].company_id
• items[].source_type
• items[].promotion_status
• meta.created

現行の public contract では companyId が必要です。company-less の list-scoped research item は deferred surface です。

Credits

sf credits balance --json
sf credits summary --json

確認する key:

• balance.available_credits
• balance.remaining_credits
• balance.reserved_credits
• balance.grants[]
• summary.totalQuantity
• summary.used_credits
• summary.remaining_credits
• summary.available_credits
• summary.reserved_credits
• summary.meterBreakdown[]
• summary.usageBreakdown[]
• summary.recentEvents[]

balance は「今実行できるか」、summary は「何が起きたか」を見る command です。summary.remaining_credits / summary.available_credits / summary.reserved_credits は現在の残高 snapshot、summary.used_credits は対象期間の消費量です。

復旧方法

次に読むページ

• endpoint contract: Lists API
• source 起点: Source Import Workflow
• credit failure: credit と maxCredits の失敗
• credit contract: Credit Schedule