Documentation

API reference

Query tool runs

GET/v1/tool-runs

Unified support for flat constant per-call pricing, input pricing precomputed from inputs, and usage pricing based on final usage. pricing.quote_required determines whether a quote is mandatory; requires_usage determines whether a cost cap and authoritative final usage are required. Neither is inferred from schema_version. When metered_pricing is off, only new calls requiring final usage are restricted; constant/input rules remain available if they need no final usage. The current key must have tool authorization; run identity and results are scoped to the original key. The catalog is empty when the master tool switch is off; the anonymous catalog is not executable authorization. Lists only runs owned by the original key, strictly ordered by created_at descending, then id descending; id provides stable tie-breaking within the same second. next_cursor is an opaque pair cursor and must be passed back unchanged; malformed cursors return 400 invalid_cursor. Pagination is not a time snapshot. Refresh the first page to see new records that sort before the current cursor.

Authentication and permissions

Use your current GloopAPI key. Available models, capabilities and permissions depend on its catalog and the endpoint documentation.

Authorization: Bearer $GLOOP_API_KEY

Authentication schemes: BearerAuth

Request

Query parameters

  • cursorstringOptional

    next_cursor from the original response; do not construct it yourself. Invalid cursors return 400 invalid_cursor.

  • limitintegerOptional

    Catalog range is 1–100, falling back to 20 for invalid values; run list range is 1–100, falling back to 20 for invalid values.

Responses and errors

HTTP 200

Tool runs queried successfully

application/json

Type
object
Required fields
items
  • itemsarrayRequired

    Array of tools or runs on the current page.

    items child fields (1)
    • []objectOptional
      [] child fields (10)
      • idstringRequired

        Public identifier of this object, used for its corresponding detail path.

      • tool_idstringRequired

        Tool ID from the current key's executable catalog.

      • versionstringRequired

        Contract/capability or tool version; runs use the tool version returned by the catalog.

      • statusstringRequired

        submitting/running/submission_unknown/succeeded/failed; submission_unknown means the submission outcome is unknown. Do not resend with a different Idempotency-Key.

      • outputunknownRequired

        JSON defined by the tool's output_schema; do not assume results remain after expiration.

      • error_codestringOptional

        Public error code usable for branching logic.

      • billingobjectRequired

        Independent billing status; do not substitute generation status.

        billing child fields (7)
        • review_requiredbooleanOptional

          Billing evidence requires manual review.

        • reasonstringOptional

          Public reason for an unavailable action or billing review.

        • usageunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • breakdownunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • statusstringRequired

          Current object status; evaluate separately from billing and the saving stage.

        • reserved_usdstringRequired

          Maximum USD reservation amount as a string.

        • charged_usdstringRequired

          Currently confirmed USD charge amount as a string.

        allOf branch 1

        Type: object

        Required in this branch: status, reserved_usd, charged_usd

        • review_requiredbooleanOptional

          Billing evidence requires manual review.

        • reasonstringOptional

          Public reason for an unavailable action or billing review.

        • usageunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • breakdownunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • statusstringRequired

          Current object status; evaluate separately from billing and the saving stage.

        • reserved_usdstringRequired

          Maximum USD reservation amount as a string.

        • charged_usdstringRequired

          Currently confirmed USD charge amount as a string.

      • result_expiredbooleanRequired

        Whether the result has expired; billing/idempotency records remain.

      • created_atintegerRequired

        Creation time in Unix seconds.

      • updated_atintegerRequired

        Last update time in Unix seconds.

  • next_cursorstringOptional

    Strictly opaque created_at/id pair cursor; pass it back unchanged. Malformed cursors return 400 invalid_cursor; a missing or empty value indicates the last page.

HTTP 400

Invalid request fields or parameters.

application/json

Type
object
Required fields
error

HTTP 401

The key is missing, invalid, expired, or revoked.

application/json

Type
object
Required fields
error

HTTP 403

Insufficient IP, account, model, or tool permissions.

application/json

Type
object
Required fields
error

HTTP 404

Object/capability unavailable, or feature switch disabled.

application/json

Type
object
Required fields
error

HTTP 409

Idempotency/quote conflict, object not ready, or still referenced.

application/json

Type
object
Required fields
error

HTTP 429

Request/queue rate limit.

application/json

Type
object
Required fields
error

HTTP 500

Internal authentication or data storage failure.

application/json

Type
object
Required fields
error

HTTP 503

Service, pricing, or storage unavailable.

application/json

Type
object
Required fields
error