> ## Documentation Index
> Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 社交数据研究

> 获取社交平台资料、帖子和搜索结果，或查找同一账号在其他平台上的资料。

Reddit、X、YouTube、TikTok、Instagram 和 LinkedIn 的公开社交数据：搜索帖子、读取账号、近期帖子或单篇帖子，以及查找同一账号在其他平台上的资料。选择 platform 和 mode，并提供 query、handle 或 url。

所有模式返回六个平台共享的规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。profile 返回单个账号，包含 platform、handle、name、url、bio、headline、website、followers、following、posts、verified；search 和 feed 返回帖子列表 output.items\[]，包含 id、url、title、text、author、author\_url、published\_at、likes、comments、shares、views；post 返回相同字段的单篇帖子；find 返回 output.profiles\[]，包含 platform、url、handle、scrapecreators\_confidence、followers，Reddit 为匹配版块，并包含 pdl\_likelihood。原生输出不在 output 中重复，保留在 Run 中，可通过 GET /v1/runs/:id 读取。平台或数据提供商未报告的值为 null。

分别检查 result\_status 和 status：前者为 success、no\_result、error 或 pending。有效空结果为 no\_result，保留模式结构，items 或 profiles 为 \[]，或各字段为 null。charge\_usd 为本响应 runs 总费用，所有 Run 结算前为 null。provider=auto 选择第一家符合条件的数据提供商，仅在 PROVIDER\_ERROR、TIMED\_OUT 或受理时 503 后尝试下一家；指定数据提供商时不切换。对于 QUEUED/RUNNING，即 Apify 路径的 HTTP 202，在 API 服务地址上使用认证轮询 result\_url。有意重试时复用相同 Idempotency-Key 和执行参数。

## 各模式输出

各模式共享的规范化字段，适用于所有平台。原生输出保留在 Run 中，可通过 GET /v1/runs/:id 读取。平台或数据提供商未报告的值为 null。

* profile: platform, handle, name, url, bio, headline, website, followers, following, posts, verified
* search: items\[]: id, url, title, text, author, author\_url, published\_at, likes, comments, shares, views
* feed: items\[]: 与 search 相同的帖子字段
* post: id, url, title, text, author, author\_url, published\_at, likes, comments, shares, views
* find: profiles\[]: platform, url, handle, scrapecreators\_confidence, followers ，Reddit 为匹配版块; pdl\_likelihood

```json
{
  "action": "x.feed",
  "provider": "scrapecreators",
  "status": "COMPLETED",
  "result_status": "success",
  "output": {
    "items": [
      { "id": "2110166802315804689", "url": "https://x.com/stripe/status/2110166802315804689", "title": null, "text": "You can now use Underdog…", "author": "stripe", "author_url": "https://x.com/stripe", "published_at": "2026-10-14T00:32:25Z", "likes": 55, "comments": 21, "shares": 6, "views": 8447 }
    ]
  },
  "charge_usd": "0.00188",
  "runs": [{ "provider": "scrapecreators", "status": "COMPLETED", "charge_usd": "0.00188" }],
  "result_url": "/v1/solutions/gtm/social_research/result?token=…"
}
```


## OpenAPI

````yaml /openapi.zh.json post /v1/solutions/gtm/social_research
openapi: 3.1.0
info:
  title: Glasser
  version: 0.0.1
  description: 一个 API Key，无需合同，按次付费，即可调用批量采购的付费 API。每个响应包含 x-request-id；所有错误正文采用统一结构。
servers:
  - url: https://api.glasser.ai
security: []
tags:
  - name: Solutions
  - name: Endpoints
  - name: Runs
  - name: Balance
paths:
  /v1/solutions/gtm/social_research:
    post:
      tags:
        - Solutions
      summary: 社交数据研究
      description: >-
        Reddit、X、YouTube、TikTok、Instagram 和 LinkedIn
        的公开社交数据：搜索帖子、读取账号、近期帖子或单篇帖子，以及查找同一账号在其他平台上的资料。选择 platform 和 mode，并提供
        query、handle 或 url。


        所有模式返回六个平台共享的规范化 output，以及最后一个 Run 的 id、provider 和生命周期 status。profile
        返回单个账号，包含
        platform、handle、name、url、bio、headline、website、followers、following、posts、verified；search
        和 feed 返回帖子列表 output.items[]，包含
        id、url、title、text、author、author_url、published_at、likes、comments、shares、views；post
        返回相同字段的单篇帖子；find 返回 output.profiles[]，包含
        platform、url、handle、scrapecreators_confidence、followers，Reddit 为匹配版块，并包含
        pdl_likelihood。原生输出不在 output 中重复，保留在 Run 中，可通过 GET /v1/runs/:id
        读取。平台或数据提供商未报告的值为 null。


        分别检查 result_status 和 status：前者为 success、no_result、error 或 pending。有效空结果为
        no_result，保留模式结构，items 或 profiles 为 []，或各字段为 null。charge_usd 为本响应 runs
        总费用，所有 Run 结算前为 null。provider=auto 选择第一家符合条件的数据提供商，仅在
        PROVIDER_ERROR、TIMED_OUT 或受理时 503 后尝试下一家；指定数据提供商时不切换。对于 QUEUED/RUNNING，即
        Apify 路径的 HTTP 202，在 API 服务地址上使用认证轮询 result_url。有意重试时复用相同
        Idempotency-Key 和执行参数。
      operationId: gtm-social-research
      parameters:
        - name: idempotency-key
          in: header
          schema:
            type: string
            minLength: 1
            description: >-
              为每次预期执行生成唯一值，推荐使用 UUID。使用同一个键和执行参数重试，可读取原
              Run，避免再次扣费。使用同一个键但修改执行参数会返回 409；修改 task_id 或 metadata 不会更新原 Run。
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                platform:
                  type: string
                  enum:
                    - reddit
                    - x
                    - youtube
                    - tiktok
                    - instagram
                    - linkedin
                mode:
                  anyOf:
                    - type: string
                      enum:
                        - search
                        - profile
                        - feed
                        - post
                        - find
                      description: >-
                        默认为 search。每个平台都支持各个模式。


                        - search：匹配 query 的帖子。

                        - profile：根据 handle 获取账号详情；Reddit 为版块，LinkedIn 需提供个人或公司
                        url。

                        - feed：handle 的近期帖子或视频；LinkedIn 需提供公司 url。

                        - post：根据 url 获取单篇帖子或视频。

                        - find：根据 handle 查找其他社交平台资料；LinkedIn 需提供个人资料 url；Reddit
                        使用 query 查找版块。
                    - type: 'null'
                provider:
                  anyOf:
                    - type: string
                      enum:
                        - auto
                        - scrapecreators
                        - apify
                        - tikhub
                        - pdl
                      description: >-
                        默认为 auto，按 Glasser
                        偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key
                        的允许，不会切换到其他家。可用值见下方。
                    - type: 'null'
                query:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 500
                    - type: 'null'
                handle:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 100
                      description: 用户名，不含 @；或 Reddit 版块名，不含 r/。
                    - type: 'null'
                url:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 2048
                    - type: 'null'
                task_id:
                  anyOf:
                    - type: string
                      description: >-
                        将相关 Run，包括自动切换产生的 Run，归入同一个 Task。复用稳定字符串，并通过 Task 筛选 Run
                        列表。
                    - type: 'null'
                metadata:
                  anyOf:
                    - anyOf:
                        - type: object
                          additionalProperties:
                            type: string
                            minLength: 1
                            maxLength: 500
                          maxProperties: 20
                          propertyNames:
                            type: string
                            pattern: ^[a-z][a-z0-9_]{0,39}$
                        - {}
                      description: |-
                        可选追踪字段，随 Run 返回，也可用于筛选。不会发送给数据提供商，也不影响路由、价格或幂等。

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

                        无效条目整体丢弃，不截断。请求继续执行，Run 返回实际保存的字段。
                    - type: 'null'
              required:
                - platform
              additionalProperties: false
        required: true
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/SocialResearchResult'
        '202':
          description: 成功
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/SocialResearchResult'
        '400':
          description: ValidationFailed | IdempotencyKeyRequired
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
                  - $ref: '#/components/schemas/IdempotencyKeyRequiredEncoded'
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '402':
          description: InsufficientBalance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientBalanceEncoded'
        '403':
          description: EndpointNotPermitted | Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/EndpointNotPermittedEncoded'
                  - $ref: '#/components/schemas/ForbiddenEncoded'
        '409':
          description: IdempotencyConflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyConflictEncoded'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedEncoded'
        '503':
          description: ServiceUnavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableEncoded'
      security:
        - bearer: []
components:
  schemas:
    SocialResearchResult:
      type: object
      properties:
        id:
          type: string
        run_url:
          type: string
          description: 在控制台打开 Run，需要工作空间成员权限。
        provider:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]*$
        endpoint:
          type: string
          pattern: ^\/.+$
        endpoint_version:
          type: integer
          exclusiveMinimum: 0
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - COMPLETED
            - FAILED
            - STOPPED
          description: >-
            QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx 响应。FAILED 请读取
            failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。
        failure:
          anyOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - TIMED_OUT
                    - INTERNAL
                message:
                  type: string
              required:
                - kind
                - message
              additionalProperties: false
            - type: 'null'
          description: Run 失败原因，仅在 status 为 FAILED 时非 null。
        input:
          type: object
        output:
          anyOf:
            - anyOf:
                - type: object
                  properties:
                    platform:
                      anyOf:
                        - type: string
                        - type: 'null'
                    handle:
                      anyOf:
                        - type: string
                        - type: 'null'
                    name:
                      anyOf:
                        - type: string
                        - type: 'null'
                    url:
                      anyOf:
                        - type: string
                        - type: 'null'
                    bio:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 自由文本简介；LinkedIn 为 About 部分。
                    headline:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: LinkedIn 个人资料标题，即职称行；其他平台为 null。
                    website:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 账号自有网站：LinkedIn 为公司网站，X 为展开后的资料链接，不使用 t.co；其他平台为 null。
                    followers:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: 粉丝数；Reddit 为版块订阅人数，YouTube 为订阅人数。
                    following:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: 此账号关注的账号数；Reddit、YouTube 和 LinkedIn 为 null。
                    posts:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    verified:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                  required:
                    - platform
                    - handle
                    - name
                    - url
                    - bio
                    - headline
                    - website
                    - followers
                    - following
                    - posts
                    - verified
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              平台帖子 ID；LinkedIn 为裸 activity ID，不含
                              urn:li:activity: 前缀。
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          title:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: Reddit 和 YouTube 的标题，其他平台为 null。
                          text:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              帖子正文：Reddit self-text、YouTube
                              描述、推文、图片说明或帖子文本。数据提供商未返回正文时为 null，例如 Reddit
                              链接帖、YouTube 搜索结果。
                          author:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              展示名称；平台不提供其他名称时使用 handle，适用于
                              X、TikTok、Instagram、Reddit。
                          author_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          published_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: ISO 8601 UTC 发布时间；数据提供商未提供准确时间时为 null。
                          likes:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: >-
                              Reddit 为赞减踩的净分，可能为负。X 为 favorites，TikTok 为
                              diggs，其他平台为点赞或反应数。
                          comments:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          shares:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: >-
                              X 为转推，TikTok 为分享面板发送次数而非转发，LinkedIn
                              为转发；Reddit、YouTube 和 Instagram 为 null。
                          views:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: >-
                              X 为曝光，TikTok 为播放，YouTube 为观看，Instagram
                              为视频观看；Reddit 和 LinkedIn 为 null。
                        required:
                          - id
                          - url
                          - title
                          - text
                          - author
                          - author_url
                          - published_at
                          - likes
                          - comments
                          - shares
                          - views
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    id:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: '平台帖子 ID；LinkedIn 为裸 activity ID，不含 urn:li:activity: 前缀。'
                    url:
                      anyOf:
                        - type: string
                        - type: 'null'
                    title:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: Reddit 和 YouTube 的标题，其他平台为 null。
                    text:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: >-
                        帖子正文：Reddit self-text、YouTube
                        描述、推文、图片说明或帖子文本。数据提供商未返回正文时为 null，例如 Reddit 链接帖、YouTube
                        搜索结果。
                    author:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: 展示名称；平台不提供其他名称时使用 handle，适用于 X、TikTok、Instagram、Reddit。
                    author_url:
                      anyOf:
                        - type: string
                        - type: 'null'
                    published_at:
                      anyOf:
                        - type: string
                        - type: 'null'
                      description: ISO 8601 UTC 发布时间；数据提供商未提供准确时间时为 null。
                    likes:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        Reddit 为赞减踩的净分，可能为负。X 为 favorites，TikTok 为
                        diggs，其他平台为点赞或反应数。
                    comments:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    shares:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        X 为转推，TikTok 为分享面板发送次数而非转发，LinkedIn 为转发；Reddit、YouTube 和
                        Instagram 为 null。
                    views:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        X 为曝光，TikTok 为播放，YouTube 为观看，Instagram 为视频观看；Reddit 和
                        LinkedIn 为 null。
                  required:
                    - id
                    - url
                    - title
                    - text
                    - author
                    - author_url
                    - published_at
                    - likes
                    - comments
                    - shares
                    - views
                  additionalProperties: false
                - type: object
                  properties:
                    profiles:
                      type: array
                      items:
                        type: object
                        properties:
                          platform:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              小写社交平台名。六个 social_research 平台使用请求名称，twitter 为
                              x；其他平台如 facebook、github 原样保留。
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          handle:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: 该平台用户名，可作为 social_research 的 handle；未提供时为 null。
                          scrapecreators_confidence:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: ScrapeCreators 对资料属于该账号的 0–1 置信度；其他数据提供商为 null。
                          followers:
                            anyOf:
                              - type: integer
                              - type: 'null'
                            description: reddit.find 为版块订阅人数，其他平台为 null。
                        required:
                          - platform
                          - url
                          - handle
                          - scrapecreators_confidence
                          - followers
                        additionalProperties: false
                    pdl_likelihood:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        People Data Labs 对人员记录与输入匹配程度的 1–10
                        分数，针对整个人员而非单个平台资料。仅用于 linkedin.find，其他情况为 null。
                  required:
                    - profiles
                    - pdl_likelihood
                  additionalProperties: false
            - type: 'null'
          description: >-
            各模式共享的规范化字段，适用于所有平台。原生输出保留在 Run 中，可通过 GET /v1/runs/:id
            读取。平台或数据提供商未报告的值为 null。


            - profile: platform, handle, name, url, bio, headline, website,
            followers, following, posts, verified

            - search: items[]: id, url, title, text, author, author_url,
            published_at, likes, comments, shares, views

            - feed: items[]: 与 search 相同的帖子字段

            - post: id, url, title, text, author, author_url, published_at,
            likes, comments, shares, views

            - find: profiles[]: platform, url, handle,
            scrapecreators_confidence, followers ，Reddit 为匹配版块; pdl_likelihood
        provider_response:
          anyOf:
            - type: object
              properties:
                http_status:
                  type: integer
                  minimum: 100
                  maximum: 599
                  description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。
                error:
                  anyOf:
                    - {}
                    - type: 'null'
              required:
                - http_status
              additionalProperties: false
            - type: 'null'
          description: |-
            仅在 status 为 COMPLETED 时非 null。

            - 2xx 响应：output 为任意结构的数据提供商原生 JSON；正文为空时为 null。
            - 非 2xx 响应：error 包含数据提供商错误正文，output 为 null。

            两种正文均会移除敏感字段。
        charge_usd:
          anyOf:
            - type: string
              pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
              description: 精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6 转为整数，不使用浮点数。
            - type: 'null'
          description: 此 Solution 响应所含 runs 的总费用，全部 Run 结算前为 null。每个 Run 保留各自费用；失败也可能收费。
        charge_basis:
          anyOf:
            - type: object
              properties:
                clause:
                  type: string
                  enum:
                    - rule
                    - NO_RESULT
                    - PROVIDER_ERROR
                    - TIMED_OUT
                    - INTERNAL
                quantity:
                  anyOf:
                    - type: integer
                      minimum: 0
                    - type: 'null'
              required:
                - clause
                - quantity
              additionalProperties: false
            - type: 'null'
          description: 单个 Run 的计费依据；多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。
        stoppable:
          type: boolean
          description: 当前是否可接受停止请求。不保证能在分派前停止 Run。
        stop_requested_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
          description: 请求停止的时间。如果已开始分派，Run 仍可能继续。
        created_at:
          type: string
          description: ISO 8601 UTC 时间戳。
          format: date-time
        started_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
              description: ISO 8601 UTC 时间戳。
              format: date-time
            - type: 'null'
        task_id:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 500
          maxProperties: 20
          propertyNames:
            type: string
            pattern: ^[a-z][a-z0-9_]{0,39}$
          description: |-
            已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

            - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
            - 值：长度为 1–500 的字符串。
            - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
        action:
          type: string
          pattern: ^[a-z]+\.[a-z]+$
          description: '`<platform>.<mode>`；profile 模式下的 LinkedIn 公司页面为 linkedin.company。'
        result_status:
          type: string
          enum:
            - success
            - no_result
            - error
            - pending
          description: >-
            业务交付状态，与 status 中的最终 Run 生命周期独立。no_result 为有效空结果；error
            表示数据提供商输出无法交付。
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
              additionalProperties: false
            - type: 'null'
        runs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              run_url:
                type: string
                description: 在控制台打开 Run，需要工作空间成员权限。
              provider:
                type: string
                pattern: ^[a-z0-9][a-z0-9-]*$
              endpoint:
                type: string
                pattern: ^\/.+$
              endpoint_version:
                type: integer
                exclusiveMinimum: 0
              status:
                type: string
                enum:
                  - QUEUED
                  - RUNNING
                  - COMPLETED
                  - FAILED
                  - STOPPED
                description: >-
                  QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应，包括非 2xx
                  响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。
              failure:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - TIMED_OUT
                          - INTERNAL
                      message:
                        type: string
                    required:
                      - kind
                      - message
                    additionalProperties: false
                  - type: 'null'
                description: Run 失败原因，仅在 status 为 FAILED 时非 null。
              input:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              output:
                type: object
                properties:
                  omitted:
                    type: boolean
                    enum:
                      - true
                required:
                  - omitted
                additionalProperties: false
              provider_response:
                anyOf:
                  - type: object
                    properties:
                      http_status:
                        type: integer
                        minimum: 100
                        maximum: 599
                        description: 数据提供商返回的 HTTP 状态，即使 Run 为 COMPLETED 也应检查。
                    required:
                      - http_status
                    additionalProperties: false
                  - type: 'null'
              charge_usd:
                anyOf:
                  - type: string
                    pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                    description: >-
                      精确的美元十进制字符串，小数位数为 2–6，采用唯一规范格式。求和时使用十进制运算或乘以 10^6
                      转为整数，不使用浮点数。
                  - type: 'null'
                description: >-
                  最终费用，精确的美元十进制字符串。QUEUED 或 RUNNING 时为 null。FAILED 状态的 Run
                  仍可能按接口定价产生非零费用。
              charge_basis:
                anyOf:
                  - type: object
                    properties:
                      clause:
                        type: string
                        enum:
                          - rule
                          - NO_RESULT
                          - PROVIDER_ERROR
                          - TIMED_OUT
                          - INTERNAL
                      quantity:
                        anyOf:
                          - type: integer
                            minimum: 0
                          - type: 'null'
                    required:
                      - clause
                      - quantity
                    additionalProperties: false
                  - type: 'null'
                description: 计算费用所用的价格条款。结算前或未尝试调用数据提供商时为 null。
              stoppable:
                type: boolean
                description: 当前是否可接受停止请求。不保证能在分派前停止 Run。
              stop_requested_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
                description: 请求停止的时间。如果已开始分派，Run 仍可能继续。
              created_at:
                type: string
                description: ISO 8601 UTC 时间戳。
                format: date-time
              started_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                    description: ISO 8601 UTC 时间戳。
                    format: date-time
                  - type: 'null'
              task_id:
                anyOf:
                  - type: string
                  - type: 'null'
              metadata:
                type: object
                additionalProperties:
                  type: string
                  minLength: 1
                  maxLength: 500
                maxProperties: 20
                propertyNames:
                  type: string
                  pattern: ^[a-z][a-z0-9_]{0,39}$
                description: |-
                  已保存的追踪字段，可用于筛选 Run，不发送给数据提供商，不影响路由、价格或幂等。

                  - 最多 20 个键：小写字母、数字和下划线，以字母开头，最长 40 个字符。
                  - 值：长度为 1–500 的字符串。
                  - user_id：终端用户的不透明 ID，不得使用邮箱或姓名。
            required:
              - id
              - run_url
              - provider
              - endpoint
              - endpoint_version
              - status
              - failure
              - input
              - output
              - provider_response
              - charge_usd
              - charge_basis
              - stoppable
              - stop_requested_at
              - created_at
              - started_at
              - completed_at
              - task_id
              - metadata
            additionalProperties: false
        result_url:
          type: string
          description: >-
            通过认证读取规范化结果和总费用的只读 URL 路径，配合 API 服务地址使用。不创建 Run，也不恢复切换。GET
            /v1/runs/:id 仍返回原生单个 Run。
      required:
        - id
        - run_url
        - provider
        - endpoint
        - endpoint_version
        - status
        - failure
        - input
        - output
        - provider_response
        - charge_usd
        - charge_basis
        - stoppable
        - stop_requested_at
        - created_at
        - started_at
        - completed_at
        - task_id
        - metadata
        - action
        - result_status
        - error
        - runs
        - result_url
      additionalProperties: false
    ValidationFailedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyKeyRequiredEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_key_required
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    UnauthorizedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    InsufficientBalanceEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - insufficient_balance
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    EndpointNotPermittedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - endpoint_not_permitted
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ForbiddenEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    IdempotencyConflictEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - idempotency_conflict
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    RateLimitedEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limited
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    ServiceUnavailableEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.