> ## 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. # 运行接口 > 使用按检查结果准备的输入运行接口。Glasser 会检查 API Key Policy，并在创建 Run 前预留余额。 * **200：** Run 已结束，请检查状态、数据提供商响应和费用。 * **202：** 异步 Run 仍在执行，通过[获取 Run](https://glasser.ai/docs/zh/api-reference/runs/get.md)检查结果。 已结束的 Run 仍可能包含数据提供商错误。重试时复用相同 `Idempotency-Key` 和执行参数。 ## OpenAPI ````yaml /openapi.zh.json post /v1/runs 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/runs: post: tags: - Runs summary: 运行接口 description: >- 按检查结果构造数据提供商原生输入，并运行接口。Glasser 检查 API Key Policy，并在创建 Run 前预留最高费用。拒绝时不创建 Run，也不收费。重试时复用相同 Idempotency-Key 和执行参数，避免再次执行。 - **200：**Run 已结束，请检查状态、数据提供商响应和费用。 - **202：**异步 Run 仍在执行，通过 Get Run 读取结果。同步接口始终在公布的 timeout_ms 内返回终态 Run。 COMPLETED 可能包含数据提供商错误，请检查 provider_response。状态和费用相互独立，FAILED Run 也可能产生费用。 operationId: runs-create 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: provider: type: string pattern: ^[a-z0-9][a-z0-9-]*$ endpoint: type: string pattern: ^\/.+$ input: type: object description: 数据提供商原生输入，按检查结果中的 input_schema 构造。 endpoint_version: anyOf: - type: integer exclusiveMinimum: 0 description: >- 选择受支持版本，省略则使用默认版本。兼容更新保持版本号；版本不可用或已停用时返回 409。版本不锁定价格：新 Run 使用受理时价格，已受理 Run 保留至结算。 - type: 'null' task_id: anyOf: - type: string description: 本次 Run 所属 Task，来自数据源搜索响应。仅用于分组，不影响路由、价格或幂等。 - 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: - provider - endpoint additionalProperties: false required: true responses: '200': description: 终态 Run：COMPLETED、FAILED 或 STOPPED。 content: application/json: schema: 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: {} 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: >- 最终费用，精确的美元十进制字符串。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 '202': description: 执行中的 Run：QUEUED 或 RUNNING。 content: application/json: schema: 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: {} 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: >- 最终费用，精确的美元十进制字符串。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 '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' '404': description: NotFound content: application/json: schema: $ref: '#/components/schemas/NotFoundEncoded' '409': description: IdempotencyConflict | EndpointVersionMismatch content: application/json: schema: anyOf: - $ref: '#/components/schemas/IdempotencyConflictEncoded' - $ref: '#/components/schemas/EndpointVersionMismatchEncoded' '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: 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 NotFoundEncoded: type: object properties: error: type: object properties: code: type: string enum: - not_found 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 EndpointVersionMismatchEncoded: type: object properties: error: type: object properties: code: type: string enum: - endpoint_version_mismatch 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.