跳转到主要内容
POST
SEC 公告研究
从 11 个 action 中选择:resolve、search、section、document、events、compensation、board、audit_fees、ipo、private_placements、enforcement。受理、幂等、Key Policy 和费用沿用 Run 规则;Provider 原生数据仍在 Run 上。 章节备选须保留相同申报号及 Part/Item。filing-index 的 source_run_id 可核对来源身份。薪酬年度、申报日、接受时间和生效日期分别保留。币种及缺失值不推测;发行目标、已售金额、证券数量和净收益不能互相替代。 私募需 offering_type:form_d、form_c 或 reg_a;Reg A 支持 all、1-A、1-K、1-Z。执法需 record_type:actions、litigation、administrative 或 aaer。每次只读一个 Endpoint 和一页;总数或游标为 null 不证明已查全。 分别检查 result_status 和实际费用。较大归一输出通过完整 response_file 交付。读取 result_url 复用数据,不增加执行或 Charge。

请求头

idempotency-key
string
必填

每次独立查询都生成新的唯一值(建议使用随机 UUID),即使参数相同且发生在同一天。仅在恢复同一次预期执行时沿用原键与参数,取回原 Run,不再次扣费。同键更改执行参数返回 409;更换 task_id 或 metadata 不会创建新 Run。旧的不透明键仍可用于恢复。

Minimum string length: 1

请求体

application/json
action
enum<string>
必填
可用选项:
resolve,
search,
section,
document,
events,
compensation,
board,
audit_fees,
ipo,
private_placements,
enforcement
provider
enum<string> | null

默认为 auto,按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许,不会切换到其他家。可用值见下方。

可用选项:
auto,
secapi,
financialdatasets
ticker
string | null
Required string length: 1 - 12
cik
string | null
Minimum string length: 1
Pattern: ^\d{1,10}$
cusip
string | null
Minimum string length: 1
Pattern: ^[A-Za-z0-9]{6,9}$
name
string | null
Required string length: 1 - 100
query
string | null

Provider 原生 Lucene 条件。结构化筛选与该条件按 AND 组合,不修复原生语法。SEC API 中的无效查询可能返回空结果。

Required string length: 1 - 3500
form_types
string[] | null
Minimum array length: 1
Minimum string length: 1
accession_number
string | null
Minimum string length: 1
Pattern: ^\d{10}-\d{2}-\d{6}$
start_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
end_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
limit
integer | null
必填范围: 1 <= x <= 100
offset
integer | null
必填范围: 0 <= x <= 10000
cursor
string | null
Required string length: 1 - 2000
sort_order
enum<string> | null
可用选项:
asc,
desc
filing_url
string | null
Minimum string length: 1
url
string | null
Minimum string length: 1
form_type
enum<string> | null
可用选项:
10-K,
10-K/A,
10-Q,
10-Q/A,
8-K,
8-K/A
item
string | null

章节身份:10-K 使用 1A 或 7;10-Q 使用 part1item1 或 part2item1a;8-K 使用 4.01、4.02 或 5.02。章节代码按所请求表单和 Provider 检查。

Required string length: 1 - 30
source_run_id
string<uuid> | null
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$
year
integer | null
必填范围: 1993 <= x <= 2100
quarter
integer | null
必填范围: 1 <= x <= 4
include_exhibits
boolean | null
event_types
enum<string>[] | null
Minimum array length: 1
可用选项:
auditor_change,
non_reliance,
director_officer_change
year_from
integer | null
必填范围: 1993 <= x <= 2100
year_to
integer | null
必填范围: 1993 <= x <= 2100
executive_name
string | null
Required string length: 1 - 200
classification
enum<string> | null
可用选项:
ipo,
shell_company,
spac,
resale,
other
offering_type
enum<string> | null
可用选项:
form_d,
form_c,
reg_a
reg_a_form
enum<string> | null
可用选项:
all,
1-A,
1-K,
1-Z
record_type
enum<string> | null
可用选项:
actions,
litigation,
administrative,
aaer
max_charge_usd
string | null

精确的美元十进制字符串,小数位数为 2–6,采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数,不使用浮点数。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
task_id
string | null

将相关 Run,包括自动切换产生的 Run,归入同一个 Task。复用稳定字符串,并通过 Task 筛选 Run 列表。

metadata

可选追踪字段,随 Run 返回,也可用于筛选。不会发送给数据提供商,也不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。

无效条目整体丢弃,不截断。请求继续执行,Run 返回实际保存的字段。

响应

成功

归一的 SEC 证据保留精确公告/章节身份与来源 Run。缺失字段为 null;发行目标不等于已售金额,执法指控不等于处理结果。Provider 原生输出仍在 Run 上。结果读取免费,不恢复执行。

id
string
必填
run_url
string
必填

在控制台打开 Run,需要工作空间成员权限。

provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
必填
Pattern: ^\/.+$
endpoint_version
integer
必填
status
enum<string>
必填

QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应,包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。

可用选项:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
必填

Run 失败原因,仅在 status 为 FAILED 时非 null。

input
object
必填
output
object
必填
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

  • 2xx 响应:output 为任意结构的数据提供商原生 JSON;正文为空时为 null。
  • 非 2xx 响应:error 包含数据提供商错误正文,output 为 null。

两种正文均会移除敏感字段。

charge_usd
string | null
必填

所列 Run 的历史费用总和,包括重放或读取的 Run。所有 Run 结算前为 null。这不是当前请求的新增支出;request_charge 单独报告新增费用。失败也可能收费。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
必填

单个 Run 的计费依据;多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。

stoppable
boolean
必填

当前是否可接受停止请求。不保证能在分派前停止 Run。

stop_requested_at
string<date-time> | null
必填

请求停止的时间。如果已开始分派,Run 仍可能继续。

created_at
string<date-time>
必填

ISO 8601 UTC 时间戳。

started_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

completed_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

task_id
string | null
必填
metadata
object
必填

已保存的追踪字段,可用于筛选 Run,不发送给数据提供商,不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。
action
enum<string>
必填
可用选项:
resolve,
search,
section,
document,
events,
compensation,
board,
audit_fees,
ipo,
private_placements,
enforcement
result_status
enum<string>
必填
可用选项:
success,
no_result,
error,
pending
error
object | null
必填
runs
object[]
必填
result_url
string
必填

通过认证读取规范化结果和总费用的只读 URL 路径,配合 API 服务地址使用。不创建 Run,也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。

response_file
object

以 JSON 完整交付归一 SEC 输出,替代 output。链接只在 Run 完成后的七天文件保留期内刷新。Provider 原生文件仍通过 Get Run 读取。

review_invitation
object

每个 Run 至多出现一次,只在部分已完成 Run 的首次交付中出现。用完本次结果后,按 instruction 提交评价,然后继续任务。可选;不影响 Run 及其费用。

request_charge
object

当前请求的受理与费用证据。在同一件用户工作中保存 created_run_ids,每个已结算 Run 只计一次费用。更换 task_id 不会把幂等重放变成新 Run。读取结果的费用为零,受理列表为空。