> ## 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.

# Creator research

> Find creator accounts, group matching content by author, enrich creator profiles, find available contacts, or inspect TikTok Shop performance. Choose an action and platform and supply its required fields below.

Every action returns normalized `output`; a missing value is `null`. The Provider's native output stays on the Run and is readable with [Get Run](https://glasser.ai/docs/api-reference/runs/get.md). `search` and `content` return creator `items[]` and pagination; content discovery groups authors within one page and preserves `matching_posts[]` as evidence. `profile` returns the requested account, connected `profiles[]` and `contacts[]`. `contact` returns `contacts[]`. `shop` returns the creator, Kalodata id, market, currency, period, separate sales metrics and contacts. Preserve contact `usage` and `verified`; unknown values do not mean business or verified. Provider engagement percentages and Kalodata estimates keep their original meaning.

Read `result_status` separately from Run `status`. `no_result` keeps the action's empty shape. `charge_usd` totals the listed `runs` and remains null until they settle. Read a pending result through its authenticated `result_url`; this creates no new Run and does not resume fallback.


## OpenAPI

````yaml /openapi.json post /v1/solutions/gtm/creator_research
openapi: 3.1.0
info:
  title: Glasser
  version: 0.0.1
  description: >-
    One key, no contract, pay per call, across paid APIs bought wholesale. Every
    response carries x-request-id; every error body carries the same envelope.
servers:
  - url: https://api.glasser.ai
security: []
tags:
  - name: Solutions
  - name: Endpoints
  - name: Runs
  - name: Balance
paths:
  /v1/solutions/gtm/creator_research:
    post:
      tags:
        - Solutions
      summary: Creator research
      description: >-
        Discover creator accounts, group matching content by author, enrich
        cross-platform profiles, find contacts, or inspect TikTok Shop
        performance. Use action and platform with the action-specific inputs.
        Output is normalized; missing values are null. Contacts preserve the
        Provider's email type and verification state. Engagement and sales
        estimates retain their Provider names and units. Content discovery
        groups one page only; use next_cursor to continue and deduplicate across
        pages. Unsupported filters fail before a Run. HTTP 202 returns a signed,
        authenticated result_url to read the same Runs without another Charge.
        Provider-native output remains on GET /v1/runs/:id. provider=auto falls
        back only on Provider errors, timeouts or admission 503, never on an
        empty result.
      operationId: gtm-creator-research
      parameters:
        - name: idempotency-key
          in: header
          schema:
            type: string
            minLength: 1
            description: >-
              Generate a new unique value (prefer a random UUID) for each
              independent lookup, even with identical parameters on the same
              day. Retry the same intended execution with its original key and
              parameters to retrieve the original Run without another Charge.
              Changing execution parameters with the same key returns 409;
              changing task_id or metadata does not start a new Run. Existing
              opaque keys remain valid for recovery.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - search
                    - content
                    - profile
                    - contact
                    - shop
                platform:
                  type: string
                  enum:
                    - tiktok
                    - threads
                    - instagram
                    - youtube
                    - x
                    - twitch
                    - onlyfans
                provider:
                  anyOf:
                    - type: string
                      enum:
                        - auto
                        - scrapecreators
                        - tikhub
                        - influencersclub
                        - kalodata
                        - apify
                      description: >-
                        Default auto: select the first eligible Provider in
                        Glasser's preference order. A named Provider must
                        support the request and be allowed by your Key; it does
                        not fall back to another Provider. Available values are
                        listed below.
                    - type: 'null'
                query:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 500
                    - type: 'null'
                handle:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 2048
                    - type: 'null'
                cursor:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 4096
                    - type: 'null'
                require_email:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                  description: >-
                    profile/contact via influencersclub only: true maps to
                    email_required=must_have, false to preferred. Other
                    Providers reject this filter.
                creator_id:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 100
                    - type: 'null'
                  description: >-
                    shop only: Kalodata creator_id. Do not assume another
                    platform's user id is interchangeable.
                region:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                language:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                currency:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                date_range:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                category_ids:
                  anyOf:
                    - type: array
                      items:
                        type: integer
                    - type: 'null'
                shop_id:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: 'null'
                need_extra:
                  anyOf:
                    - type: boolean
                    - type: 'null'
                task_id:
                  anyOf:
                    - type: string
                      description: >-
                        Group related Runs, including automatic fallback, under
                        one Task. Reuse a stable string and filter the Runs list
                        by task to retrieve them.
                    - 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: >-
                        Optional tracking fields, returned on the Run and
                        available as filters. They never go to the Provider or
                        affect routing, Price, or idempotency.


                        - Up to 20 keys: lowercase letters, digits, and
                        underscores; start with a letter; at most 40 characters.

                        - Values: strings of 1–500 characters.

                        - user_id: your End user's opaque ID, never their email
                        address or name.


                        Invalid entries are dropped whole, not truncated. The
                        request continues, and the Run returns the fields that
                        were stored.
                    - type: 'null'
              required:
                - action
                - platform
              additionalProperties: false
              description: >-
                search: TikTok/Threads accounts by query; content:
                Instagram/YouTube posts by query, grouped by author within one
                page; profile: influencersclub enrichment by handle; contact:
                handle to contact details; shop: TikTok Shop detail by Kalodata
                creator_id, region, language, currency and date_range.
                Unsupported filters are rejected before a Run. Follower and
                campaign-budget screening happens after discovery; these are not
                search filters.
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreatorResearchResult'
        '202':
          description: Success
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreatorResearchResult'
        '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:
    CreatorResearchResult:
      type: object
      properties:
        id:
          type: string
        run_url:
          type: string
          description: Open this Run in the console. Requires Workspace membership.
        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 or RUNNING: still in progress. COMPLETED: a Provider response
            is available, including non-2xx responses. FAILED: read failure.
            STOPPED: stopped before dispatch. Read charge_usd separately from
            status.
        failure:
          anyOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - TIMED_OUT
                    - INTERNAL
                message:
                  type: string
              required:
                - kind
                - message
              additionalProperties: false
            - type: 'null'
          description: Why the Run failed. Non-null only when status is FAILED.
        input:
          anyOf:
            - type: object
            - type: array
              items:
                type: object
        output:
          anyOf:
            - anyOf:
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          platform:
                            anyOf:
                              - type: string
                              - type: 'null'
                          id:
                            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'
                          followers:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          following:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          posts:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          influencersclub_engagement_percent:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: >-
                              Influencers.club's engagement_percent, unchanged.
                              Its sampling and formula can differ from a rate
                              calculated from recent posts.
                          matching_posts:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                url:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                title:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                text:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                                published_at:
                                  anyOf:
                                    - type: string
                                    - type: 'null'
                              required:
                                - id
                                - url
                                - title
                                - text
                                - published_at
                              additionalProperties: false
                        required:
                          - platform
                          - id
                          - handle
                          - name
                          - url
                          - bio
                          - followers
                          - following
                          - posts
                          - verified
                          - influencersclub_engagement_percent
                          - matching_posts
                        additionalProperties: false
                    next_cursor:
                      anyOf:
                        - type: string
                        - type: 'null'
                    has_more:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                    total_matches:
                      anyOf:
                        - type: integer
                        - type: 'null'
                      description: >-
                        Provider-reported total matching accounts; null for
                        content discovery. Never the number of sampled authors.
                  required:
                    - items
                    - next_cursor
                    - has_more
                    - total_matches
                  additionalProperties: false
                - type: object
                  properties:
                    platform:
                      anyOf:
                        - type: string
                        - type: 'null'
                    id:
                      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'
                    followers:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    following:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    posts:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    verified:
                      anyOf:
                        - type: boolean
                        - type: 'null'
                    influencersclub_engagement_percent:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                      description: >-
                        Influencers.club's engagement_percent, unchanged. Its
                        sampling and formula can differ from a rate calculated
                        from recent posts.
                    profiles:
                      type: array
                      items:
                        type: object
                        properties:
                          platform:
                            anyOf:
                              - type: string
                              - type: 'null'
                          id:
                            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'
                          followers:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          following:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          posts:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          influencersclub_engagement_percent:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                            description: >-
                              Influencers.club's engagement_percent, unchanged.
                              Its sampling and formula can differ from a rate
                              calculated from recent posts.
                        required:
                          - platform
                          - id
                          - handle
                          - name
                          - url
                          - bio
                          - followers
                          - following
                          - posts
                          - verified
                          - influencersclub_engagement_percent
                        additionalProperties: false
                    contacts:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            anyOf:
                              - type: string
                              - type: 'null'
                          value:
                            anyOf:
                              - type: string
                              - type: 'null'
                          usage:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Provider-reported contact type, such as business
                              or personal. Null when unknown; an email is not
                              assumed to be a business email.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Only the Provider's explicit verification result;
                              null when not reported.
                          source_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - type
                          - value
                          - usage
                          - verified
                          - source_url
                        additionalProperties: false
                  required:
                    - platform
                    - id
                    - handle
                    - name
                    - url
                    - bio
                    - followers
                    - following
                    - posts
                    - verified
                    - influencersclub_engagement_percent
                    - profiles
                    - contacts
                  additionalProperties: false
                - type: object
                  properties:
                    contacts:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            anyOf:
                              - type: string
                              - type: 'null'
                          value:
                            anyOf:
                              - type: string
                              - type: 'null'
                          usage:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Provider-reported contact type, such as business
                              or personal. Null when unknown; an email is not
                              assumed to be a business email.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Only the Provider's explicit verification result;
                              null when not reported.
                          source_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - type
                          - value
                          - usage
                          - verified
                          - source_url
                        additionalProperties: false
                  required:
                    - contacts
                  additionalProperties: false
                - type: object
                  properties:
                    creator:
                      type: object
                      properties:
                        platform:
                          anyOf:
                            - type: string
                            - type: 'null'
                        id:
                          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'
                        followers:
                          anyOf:
                            - type: integer
                            - type: 'null'
                        following:
                          anyOf:
                            - type: integer
                            - type: 'null'
                        posts:
                          anyOf:
                            - type: integer
                            - type: 'null'
                        verified:
                          anyOf:
                            - type: boolean
                            - type: 'null'
                        influencersclub_engagement_percent:
                          anyOf:
                            - anyOf:
                                - type: number
                                - type: string
                                  enum:
                                    - Infinity
                                    - '-Infinity'
                                    - NaN
                            - type: 'null'
                          description: >-
                            Influencers.club's engagement_percent, unchanged.
                            Its sampling and formula can differ from a rate
                            calculated from recent posts.
                      required:
                        - platform
                        - id
                        - handle
                        - name
                        - url
                        - bio
                        - followers
                        - following
                        - posts
                        - verified
                        - influencersclub_engagement_percent
                      additionalProperties: false
                    kalodata_creator_id:
                      anyOf:
                        - type: string
                        - type: 'null'
                    region:
                      anyOf:
                        - type: string
                        - type: 'null'
                    currency:
                      anyOf:
                        - type: string
                        - type: 'null'
                    date_range:
                      anyOf:
                        - type: string
                        - type: 'null'
                    kalodata_revenue:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    kalodata_video_revenue:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    kalodata_live_revenue:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    kalodata_sales:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    kalodata_video_views:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    kalodata_live_views:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    contacts:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            anyOf:
                              - type: string
                              - type: 'null'
                          value:
                            anyOf:
                              - type: string
                              - type: 'null'
                          usage:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              Provider-reported contact type, such as business
                              or personal. Null when unknown; an email is not
                              assumed to be a business email.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Only the Provider's explicit verification result;
                              null when not reported.
                          source_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - type
                          - value
                          - usage
                          - verified
                          - source_url
                        additionalProperties: false
                  required:
                    - creator
                    - kalodata_creator_id
                    - region
                    - currency
                    - date_range
                    - kalodata_revenue
                    - kalodata_video_revenue
                    - kalodata_live_revenue
                    - kalodata_sales
                    - kalodata_video_views
                    - kalodata_live_views
                    - contacts
                  additionalProperties: false
                  description: >-
                    Kalodata's estimates, in the returned currency and date
                    range. No currency conversion or price estimate is applied.
            - type: 'null'
        response_file:
          type: object
          properties:
            body_field:
              type: string
              enum:
                - output
                - provider_response.error
            state:
              type: string
              enum:
                - available
                - link_pending
                - expired
                - unavailable
            download_url:
              anyOf:
                - type: string
                - type: 'null'
            link_expires_at:
              anyOf:
                - type: string
                  description: ISO-8601 UTC timestamp
                  format: date-time
                - type: 'null'
            file_expires_at:
              type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            bytes:
              type: integer
              minimum: 0
            sha256:
              type: string
            content_type:
              type: string
              enum:
                - application/json
          required:
            - body_field
            - state
            - download_url
            - link_expires_at
            - file_expires_at
            - bytes
            - sha256
            - content_type
          additionalProperties: false
          description: >-
            Complete large Provider body, delivered as a JSON file. Glasser
            applies a 32 MiB runtime resource guard to captured bodies and
            serialized files. body_field identifies the replaced field; output
            is null or provider_response.error is omitted. Download URLs expire
            after at most one hour. Authenticated Get Run refreshes the URL
            while the file is available, for 7 days. Reads and downloads do not
            execute or charge another Run. If state is link_pending, read the
            same Run to prepare the link without another execution or charge.
            The URL grants temporary read access: share it only with intended
            recipients.
        provider_response:
          anyOf:
            - type: object
              properties:
                http_status:
                  type: integer
                  minimum: 100
                  maximum: 599
                  description: >-
                    HTTP status returned by the Provider. Check this even when
                    the Run is COMPLETED.
                error:
                  anyOf:
                    - {}
                    - type: 'null'
              required:
                - http_status
              additionalProperties: false
            - type: 'null'
          description: >-
            Non-null only when status is COMPLETED.


            - For 2xx responses, output contains Provider-native JSON (any
            shape), or null for an empty body.

            - For non-2xx responses, error contains the Provider's error body
            and output is null.


            Sensitive fields are removed from both bodies.
        charge_usd:
          anyOf:
            - type: string
              pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
              description: >-
                Exact USD decimal string (min 2, max 6 decimals, one canonical
                spelling). Sum with decimal arithmetic or scale by 10^6 — never
                floats.
            - type: 'null'
          description: >-
            Historical total Charge of the listed Runs, including replayed or
            read Runs. Null until all listed Runs settle. This is not new
            spending by the current request; request_charge reports that
            separately. Failures can also be charged.
        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: >-
            Single-Run charge basis, or null for a multi-Run total. Read
            runs[].charge_basis for each charge.
        stoppable:
          type: boolean
          description: >-
            Whether a stop request can currently be accepted. This does not
            guarantee that the Run can stop before dispatch.
        stop_requested_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            - type: 'null'
          description: >-
            When a stop was requested. The Run can still continue if dispatch
            had already started.
        created_at:
          type: string
          description: ISO-8601 UTC timestamp
          format: date-time
        started_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              format: date-time
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
              description: ISO-8601 UTC timestamp
              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: >-
            Your stored tracking fields. Use them to filter Runs. They never go
            to the Provider or affect routing, Price, or idempotency.


            - Up to 20 keys: lowercase letters, digits, and underscores; start
            with a letter; at most 40 characters.

            - Values: strings of 1–500 characters.

            - user_id: your End user's opaque ID, never their email address or
            name.
        review_invitation:
          type: object
          properties:
            run_id:
              type: string
            ratings:
              type: array
              items:
                type: string
                enum:
                  - exceeds_expectations
                  - meets_expectations
                  - partially_meets_expectations
                  - does_not_meet_expectations
                  - unable_to_assess
            instruction:
              type: string
          required:
            - run_id
            - ratings
            - instruction
          additionalProperties: false
          description: >-
            Present at most once per Run, on the first delivery of some
            completed Runs. After you use this result for the task, submit a
            review as the instruction says, then continue. Optional; it never
            affects the Run or its charge.
        action:
          type: string
          enum:
            - search
            - content
            - profile
            - contact
            - shop
        result_status:
          type: string
          enum:
            - success
            - no_result
            - error
            - pending
        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: Open this Run in the console. Requires Workspace membership.
              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 or RUNNING: still in progress. COMPLETED: a Provider
                  response is available, including non-2xx responses. FAILED:
                  read failure. STOPPED: stopped before dispatch. Read
                  charge_usd separately from status.
              failure:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - TIMED_OUT
                          - INTERNAL
                      message:
                        type: string
                    required:
                      - kind
                      - message
                    additionalProperties: false
                  - type: 'null'
                description: Why the Run failed. Non-null only when status is FAILED.
              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
              response_file:
                type: object
                properties:
                  body_field:
                    type: string
                    enum:
                      - output
                      - provider_response.error
                  state:
                    type: string
                    enum:
                      - available
                      - link_pending
                      - expired
                      - unavailable
                  download_url:
                    anyOf:
                      - type: string
                      - type: 'null'
                  link_expires_at:
                    anyOf:
                      - type: string
                        description: ISO-8601 UTC timestamp
                        format: date-time
                      - type: 'null'
                  file_expires_at:
                    type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  bytes:
                    type: integer
                    minimum: 0
                  sha256:
                    type: string
                  content_type:
                    type: string
                    enum:
                      - application/json
                required:
                  - body_field
                  - state
                  - download_url
                  - link_expires_at
                  - file_expires_at
                  - bytes
                  - sha256
                  - content_type
                additionalProperties: false
                description: >-
                  Complete large Provider body, delivered as a JSON file.
                  Glasser applies a 32 MiB runtime resource guard to captured
                  bodies and serialized files. body_field identifies the
                  replaced field; output is null or provider_response.error is
                  omitted. Download URLs expire after at most one hour.
                  Authenticated Get Run refreshes the URL while the file is
                  available, for 7 days. Reads and downloads do not execute or
                  charge another Run. If state is link_pending, read the same
                  Run to prepare the link without another execution or charge.
                  The URL grants temporary read access: share it only with
                  intended recipients.
              provider_response:
                anyOf:
                  - type: object
                    properties:
                      http_status:
                        type: integer
                        minimum: 100
                        maximum: 599
                        description: >-
                          HTTP status returned by the Provider. Check this even
                          when the Run is 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: >-
                      Exact USD decimal string (min 2, max 6 decimals, one
                      canonical spelling). Sum with decimal arithmetic or scale
                      by 10^6 — never floats.
                  - type: 'null'
                description: >-
                  Final charge as an exact USD decimal string. Null while QUEUED
                  or RUNNING. A FAILED Run can have a non-zero charge under the
                  Endpoint's Price.
              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: >-
                  Price clause used to calculate the charge. Null before
                  settlement or when no Provider attempt was made.
              stoppable:
                type: boolean
                description: >-
                  Whether a stop request can currently be accepted. This does
                  not guarantee that the Run can stop before dispatch.
              stop_requested_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  - type: 'null'
                description: >-
                  When a stop was requested. The Run can still continue if
                  dispatch had already started.
              created_at:
                type: string
                description: ISO-8601 UTC timestamp
                format: date-time
              started_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    format: date-time
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                    description: ISO-8601 UTC timestamp
                    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: >-
                  Your stored tracking fields. Use them to filter Runs. They
                  never go to the Provider or affect routing, Price, or
                  idempotency.


                  - Up to 20 keys: lowercase letters, digits, and underscores;
                  start with a letter; at most 40 characters.

                  - Values: strings of 1–500 characters.

                  - user_id: your End user's opaque ID, never their email
                  address or name.
            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
        request_charge:
          type: object
          properties:
            charge_usd:
              anyOf:
                - type: string
                  pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
                  description: >-
                    Exact USD decimal string (min 2, max 6 decimals, one
                    canonical spelling). Sum with decimal arithmetic or scale by
                    10^6 — never floats.
                - type: 'null'
              description: >-
                Charge for Runs created by this request only. Replayed Runs and
                free reads add zero. Null while a newly created Run is unsettled
                or its admission source is unknown. This is not the historical
                total in charge_usd or runs[].charge_usd.
            created_run_ids:
              type: array
              items:
                type: string
                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})$
                format: uuid
            replayed_run_ids:
              type: array
              items:
                type: string
                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})$
                format: uuid
            unknown_run_ids:
              type: array
              items:
                type: string
                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})$
                format: uuid
          required:
            - charge_usd
            - created_run_ids
            - replayed_run_ids
            - unknown_run_ids
          additionalProperties: false
          description: >-
            Request-scoped admission and Charge evidence. Record created_run_ids
            across the user's work, then count each settled Run once. Changing
            task_id does not turn an idempotent replay into a new Run. A result
            read has zero Charge and empty admission lists.
        result_url:
          type: string
          description: >-
            Authenticated, read-only URL path for polling this normalized result
            and total charge. Use with the API origin. Does not create Runs or
            resume fallback. GET /v1/runs/:id still returns the native,
            individual 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.