跳转到主要内容
POST
股票研究
选择 action 及其期别或模式。每个请求创建一个 Run;缺失值保持 null。财务比率采用小数,宏观利率采用百分数。分别读取 result_status 和 charge_usd。筛选前使用 action: screen 与 describe_filters: true 读取可用字段。Provider 原生输出保留在 Run 上。

请求头

idempotency-key
string
必填

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

Minimum string length: 1

请求体

application/json

每个请求执行一次 FinancialDatasets 操作。未使用的字段在收费前被拒绝。空数据仍可能收费。不换汇、不估算缺失值、不自动翻页。

action
enum<string>
必填
可用选项:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
provider
enum<string> | null

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

可用选项:
auto,
financialdatasets
ticker
string | null
Minimum string length: 1
Pattern: ^[A-Za-z0-9.-]{1,12}$
cik
string | null
Minimum string length: 1
Pattern: ^\d{1,10}$
period
enum<string> | null
可用选项:
annual,
quarterly,
ttm
mode
enum<string> | null

仅用于 metrics/prices/macro;默认 snapshot。history 需要对应 action 的期别或日期参数。

可用选项:
snapshot,
history
statement
enum<string> | null
可用选项:
all,
income,
balance_sheet,
cash_flow
macro
enum<string> | null
可用选项:
interest_rates,
inflation,
yield_curve,
banks,
inflation_series
bank
string | null
Required string length: 1 - 200
series
string | null
Required string length: 1 - 200
limit
integer | null
必填范围: 1 <= x <= 100
cursor
string | null
Required string length: 1 - 2000
interval
enum<string> | null
可用选项:
day,
week,
month,
year
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}$
metric_name
string | null
Required string length: 1 - 200
filters
object[] | null
Required array length: 1 - 20 elements
describe_filters
boolean | null

仅用于 screen:true 免费读取可用字段、别名、运算符和公司分类标签;此时拒绝 filters 和 limit。

report_period
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
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 返回实际保存的字段。

响应

成功

财务金额保留币种;比率与增长率保持原始小数(0.3 表示 30%)。宏观利率与股价 day_change_percent 是百分数。缺失字段为 null。Run completed_at 是取数时间,不能代替观察日期。

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>
必填
可用选项:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
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 文件完整交付较大的 Provider 正文。Glasser 对接收的正文和序列化文件应用 32 MiB 的运行时资源保护。body_field 指明被替代的字段;output 为 null,或省略 provider_response.error。下载链接最多一小时后过期。在文件的 7 天可用期内,通过已认证的 Get Run 刷新链接。读取和下载不会再次执行 Run 或重复收费。state 为 link_pending 时,读取同一 Run 即可准备链接,不会再次执行或重复收费。链接授予临时读取权限,请仅与预期接收者分享。

review_invitation
object

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

request_charge
object

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