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

# Investigación de creadores

> Busca cuentas de creadores, agrupa contenido por autor, completa perfiles, encuentra contactos o consulta el rendimiento en TikTok Shop. Elige action y platform y proporciona los campos requeridos.

Cada acción devuelve output normalizado; los valores ausentes son null. La respuesta nativa del Provider permanece en el Run y se puede leer con Get Run. search y content devuelven items\[] de creadores y paginación; content agrupa autores dentro de una página y conserva matching\_posts\[] como evidencia. profile devuelve la cuenta solicitada, profiles\[] conectados y contacts\[]. contact devuelve contacts\[]. shop devuelve la cuenta, el id de Kalodata, mercado, moneda, periodo, métricas de ventas separadas y contactos. Conserva usage y verified; desconocido no significa comercial ni verificado. Los porcentajes del Provider y las estimaciones de Kalodata mantienen su significado.

Lee result\_status por separado de status del Run. no\_result conserva la estructura vacía de la acción. charge\_usd suma los runs indicados y permanece null hasta la liquidación. Lee los resultados pendientes mediante result\_url autenticado: no crea otro Run ni reanuda alternativas.


## OpenAPI

````yaml /openapi.es.json post /v1/solutions/gtm/creator_research
openapi: 3.1.0
info:
  title: Glasser
  version: 0.0.1
  description: >-
    Una API Key, sin contrato, con pago por llamada, para APIs de pago
    adquiridas al por mayor. Cada respuesta incluye x-request-id; cada cuerpo de
    error incluye el mismo sobre.
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: Investigación de creadores
      description: >-
        Descubre cuentas de creadores, agrupa contenido por autor, completa
        perfiles, busca contactos o consulta el rendimiento en TikTok Shop. Usa
        action, platform y los parámetros de cada acción. output está
        normalizado y los valores ausentes son null. Los contactos conservan el
        tipo de correo y la verificación del Provider. Las métricas conservan el
        Provider y sus unidades. La agrupación abarca una página; usa
        next_cursor y elimina duplicados entre páginas. Los filtros
        incompatibles se rechazan antes del Run. HTTP 202 devuelve result_url
        firmado y autenticado para leer los mismos Runs sin otro Charge. La
        respuesta nativa sigue en GET /v1/runs/:id. provider=auto solo cambia de
        Provider ante errores, tiempos de espera o admisión 503, nunca por
        resultados vacíos.
      operationId: gtm-creator-research
      parameters:
        - name: idempotency-key
          in: header
          schema:
            type: string
            minLength: 1
            description: >-
              Genere un valor único nuevo (preferiblemente un UUID aleatorio)
              para cada consulta independiente, incluso con los mismos
              parámetros el mismo día. Recupere la misma ejecución con su clave
              y parámetros originales para obtener el Run original sin otro
              cargo. Cambiar los parámetros de ejecución con la misma clave
              devuelve 409; cambiar task_id o metadata no inicia un Run nuevo.
              Las claves opacas existentes siguen siendo válidas para
              recuperación.
          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: >-
                        Auto predeterminado: selecciona el primer proveedor de
                        datos elegible según el orden de preferencia de Glasser.
                        Un proveedor de datos especificado debe admitir la
                        solicitud y estar permitido por tu API Key; no recurre a
                        otro proveedor de datos. Los valores disponibles se
                        muestran a continuación.
                    - 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: >-
                    Solo profile/contact mediante influencersclub: true
                    corresponde a email_required=must_have; false, a preferred.
                    Otros Providers rechazan este filtro.
                creator_id:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 100
                    - type: 'null'
                  description: >-
                    Solo shop: creator_id de Kalodata. No supongas que el ID de
                    usuario de otra plataforma es intercambiable.
                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: >-
                        Agrupa los Runs relacionados, incluido el fallback
                        automático, en un solo Task. Reutiliza una cadena
                        estable y filtra la lista de Runs por task para
                        recuperarlos.
                    - 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: >-
                        Campos de seguimiento opcionales, devueltos en el Run y
                        disponibles como filtros. Nunca se envían al proveedor
                        de datos ni afectan al enrutamiento, Price o la
                        idempotencia.


                        - Hasta 20 claves: letras minúsculas, dígitos y guiones
                        bajos; deben comenzar con una letra y tener como máximo
                        40 caracteres.

                        - Valores: cadenas de 1–500 caracteres.

                        - user_id: el ID opaco de tu usuario final, nunca su
                        dirección de correo electrónico ni su nombre.


                        Las entradas no válidas se descartan por completo, no se
                        truncan. La solicitud continúa y el Run devuelve los
                        campos que se almacenaron.
                    - type: 'null'
              required:
                - action
                - platform
              additionalProperties: false
              description: >-
                search: cuentas de TikTok/Threads por query. content: contenido
                de Instagram/YouTube agrupado por autor en una página. profile:
                enriquecimiento por handle mediante influencersclub. contact:
                contactos por handle. shop: detalles de TikTok Shop por
                creator_id de Kalodata, region, language, currency y date_range.
                Los filtros incompatibles se rechazan antes del Run. Los
                seguidores y el presupuesto se evalúan después del
                descubrimiento, no son filtros de búsqueda.
        required: true
      responses:
        '200':
          description: Éxito
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CreatorResearchResult'
        '202':
          description: Éxito
          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: Abre este Run en la consola. Requiere pertenecer al Workspace.
        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 o RUNNING: todavía está en curso. COMPLETED: hay una
            respuesta del proveedor de datos disponible, incluidas las
            respuestas que no son 2xx. FAILED: consulta `failure`. STOPPED:
            detenido antes del dispatch. Consulta charge_usd por separado de
            status.
        failure:
          anyOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - TIMED_OUT
                    - INTERNAL
                message:
                  type: string
              required:
                - kind
                - message
              additionalProperties: false
            - type: 'null'
          description: >-
            Motivo por el que falló el Run. Solo es distinto de null cuando
            status es 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: >-
                              engagement_percent de Influencers.club sin
                              cambios. Su muestra y fórmula pueden diferir de
                              una tasa calculada con publicaciones recientes.
                          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: >-
                        Total de cuentas coincidentes informado por el Provider;
                        null para content. Nunca es el número de autores de la
                        muestra.
                  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: >-
                        engagement_percent de Influencers.club sin cambios. Su
                        muestra y fórmula pueden diferir de una tasa calculada
                        con publicaciones recientes.
                    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: >-
                              engagement_percent de Influencers.club sin
                              cambios. Su muestra y fórmula pueden diferir de
                              una tasa calculada con publicaciones recientes.
                        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: >-
                              Tipo de contacto informado por el Provider, como
                              comercial o personal. null si se desconoce; no se
                              supone que un correo sea comercial.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Solo el resultado explícito de verificación del
                              Provider; null cuando no se informa.
                          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: >-
                              Tipo de contacto informado por el Provider, como
                              comercial o personal. null si se desconoce; no se
                              supone que un correo sea comercial.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Solo el resultado explícito de verificación del
                              Provider; null cuando no se informa.
                          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: >-
                            engagement_percent de Influencers.club sin cambios.
                            Su muestra y fórmula pueden diferir de una tasa
                            calculada con publicaciones recientes.
                      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: >-
                              Tipo de contacto informado por el Provider, como
                              comercial o personal. null si se desconoce; no se
                              supone que un correo sea comercial.
                          verified:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                            description: >-
                              Solo el resultado explícito de verificación del
                              Provider; null cuando no se informa.
                          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: >-
                    Estimaciones de Kalodata en la moneda y el periodo
                    indicados. No se convierte la moneda ni se estima el precio
                    de colaboración.
            - 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: Marca de tiempo UTC ISO-8601
                  format: date-time
                - type: 'null'
            file_expires_at:
              type: string
              description: Marca de tiempo UTC ISO-8601
              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: >-
            Cuerpo completo de gran tamaño del proveedor de datos, entregado
            como archivo JSON. Glasser aplica un límite de recursos de 32 MiB al
            cuerpo capturado y al archivo serializado. body_field identifica el
            campo sustituido; output es null o se omite provider_response.error.
            Los enlaces de descarga caducan como máximo en una hora. Get Run con
            autenticación renueva la URL mientras el archivo esté disponible,
            durante 7 días. Las lecturas y descargas no ejecutan ni cobran otro
            Run. Si state es link_pending, consulta el mismo Run para preparar
            el enlace sin otra ejecución ni otro cargo. La URL concede acceso
            temporal de lectura: compártela solo con los destinatarios
            previstos.
        provider_response:
          anyOf:
            - type: object
              properties:
                http_status:
                  type: integer
                  minimum: 100
                  maximum: 599
                  description: >-
                    Estado HTTP devuelto por el proveedor de datos. Compruébalo
                    incluso cuando el Run esté COMPLETED.
                error:
                  anyOf:
                    - {}
                    - type: 'null'
              required:
                - http_status
              additionalProperties: false
            - type: 'null'
          description: >-
            Solo es distinto de null cuando status es COMPLETED.


            - Para respuestas 2xx, output contiene JSON nativo del proveedor de
            datos (con cualquier estructura) o null si el cuerpo está vacío.

            - Para respuestas que no son 2xx, error contiene el cuerpo del error
            del proveedor de datos y output es null.


            Los campos sensibles se eliminan de ambos cuerpos.
        charge_usd:
          anyOf:
            - type: string
              pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
              description: >-
                Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, con
                una única representación canónica). Suma con aritmética decimal
                o escala por 10^6; nunca uses números de coma flotante.
            - type: 'null'
          description: >-
            Cargo histórico total de los Runs enumerados, incluidos los
            repetidos o leídos. Es null hasta que todos se liquiden. No es gasto
            nuevo de la solicitud actual; request_charge lo informa por
            separado. Los fallos también pueden tener cargo.
        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: >-
            Base del cargo de un único Run, o null para un total de varios Runs.
            Consulta runs[].charge_basis para cada cargo.
        stoppable:
          type: boolean
          description: >-
            Indica si actualmente se puede aceptar una solicitud de detención.
            Esto no garantiza que el Run pueda detenerse antes del dispatch.
        stop_requested_at:
          anyOf:
            - type: string
              description: Marca de tiempo UTC ISO-8601
              format: date-time
            - type: 'null'
          description: >-
            Momento en que se solicitó la detención. El Run puede continuar si
            el dispatch ya había comenzado.
        created_at:
          type: string
          description: Marca de tiempo UTC ISO-8601
          format: date-time
        started_at:
          anyOf:
            - type: string
              description: Marca de tiempo UTC ISO-8601
              format: date-time
            - type: 'null'
        completed_at:
          anyOf:
            - type: string
              description: Marca de tiempo UTC ISO-8601
              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: >-
            Tus campos de seguimiento almacenados. Úsalos para filtrar Runs.
            Nunca se envían al proveedor de datos ni afectan al enrutamiento,
            Price o la idempotencia.


            - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben
            comenzar por una letra; como máximo 40 caracteres.

            - Valores: cadenas de 1–500 caracteres.

            - user_id: el ID opaco de tu usuario final, nunca su dirección de
            correo electrónico ni su nombre.
        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: >-
            Aparece como máximo una vez por Run, en la primera entrega de
            algunos Runs completados. Después de usar este resultado en la
            tarea, envía una reseña como indica instruction y continúa. Es
            opcional; nunca afecta al Run ni a su cargo.
        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: Abre este Run en la consola. Requiere pertenecer al Workspace.
              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 o RUNNING: todavía está en curso. COMPLETED: hay una
                  respuesta del proveedor de datos disponible, incluidas las
                  respuestas que no son 2xx. FAILED: consulta `failure`.
                  STOPPED: detenido antes del dispatch. Consulta charge_usd por
                  separado de status.
              failure:
                anyOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        enum:
                          - TIMED_OUT
                          - INTERNAL
                      message:
                        type: string
                    required:
                      - kind
                      - message
                    additionalProperties: false
                  - type: 'null'
                description: >-
                  Motivo por el que falló el Run. Solo es distinto de null
                  cuando status es 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: Marca de tiempo UTC ISO-8601
                        format: date-time
                      - type: 'null'
                  file_expires_at:
                    type: string
                    description: Marca de tiempo UTC ISO-8601
                    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: >-
                  Cuerpo completo de gran tamaño del proveedor de datos,
                  entregado como archivo JSON. Glasser aplica un límite de
                  recursos de 32 MiB al cuerpo capturado y al archivo
                  serializado. body_field identifica el campo sustituido; output
                  es null o se omite provider_response.error. Los enlaces de
                  descarga caducan como máximo en una hora. Get Run con
                  autenticación renueva la URL mientras el archivo esté
                  disponible, durante 7 días. Las lecturas y descargas no
                  ejecutan ni cobran otro Run. Si state es link_pending,
                  consulta el mismo Run para preparar el enlace sin otra
                  ejecución ni otro cargo. La URL concede acceso temporal de
                  lectura: compártela solo con los destinatarios previstos.
              provider_response:
                anyOf:
                  - type: object
                    properties:
                      http_status:
                        type: integer
                        minimum: 100
                        maximum: 599
                        description: >-
                          Estado HTTP devuelto por el proveedor de datos.
                          Compruébalo incluso cuando el Run esté 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: >-
                      Cadena decimal exacta en USD (mínimo 2 y máximo 6
                      decimales, con una única representación canónica). Suma
                      con aritmética decimal o escala por 10^6; nunca uses
                      números de coma flotante.
                  - type: 'null'
                description: >-
                  Cargo final como cadena decimal exacta en USD. Es null
                  mientras está QUEUED o RUNNING. Un Run FAILED puede tener un
                  cargo distinto de cero según el Price del Endpoint.
              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: >-
                  Cláusula de Price utilizada para calcular el cargo. Es null
                  antes de la liquidación o cuando no se realizó ningún intento
                  con el proveedor de datos.
              stoppable:
                type: boolean
                description: >-
                  Indica si actualmente se puede aceptar una solicitud de
                  detención. Esto no garantiza que el Run pueda detenerse antes
                  del dispatch.
              stop_requested_at:
                anyOf:
                  - type: string
                    description: Marca de tiempo UTC ISO-8601
                    format: date-time
                  - type: 'null'
                description: >-
                  Momento en que se solicitó la detención. El Run puede
                  continuar si el dispatch ya había comenzado.
              created_at:
                type: string
                description: Marca de tiempo UTC ISO-8601
                format: date-time
              started_at:
                anyOf:
                  - type: string
                    description: Marca de tiempo UTC ISO-8601
                    format: date-time
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                    description: Marca de tiempo UTC ISO-8601
                    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: >-
                  Tus campos de seguimiento almacenados. Úsalos para filtrar
                  Runs. Nunca se envían al proveedor de datos ni afectan al
                  enrutamiento, Price o la idempotencia.


                  - Hasta 20 claves: letras minúsculas, dígitos y guiones bajos;
                  deben comenzar por una letra; como máximo 40 caracteres.

                  - Valores: cadenas de 1–500 caracteres.

                  - user_id: el ID opaco de tu usuario final, nunca su dirección
                  de correo electrónico ni su nombre.
            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: >-
                    Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales,
                    una única escritura canónica). Suma con aritmética decimal o
                    escala por 10^6; nunca uses números de coma flotante.
                - type: 'null'
              description: >-
                Cargo solo de los Runs creados por esta solicitud. Los Runs
                repetidos y las lecturas gratuitas añaden cero. Es null mientras
                un Run nuevo siga sin liquidar o se desconozca su origen de
                admisión. No es el total histórico de charge_usd o
                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: >-
            Evidencia de admisión y cargo de la solicitud actual. Conserve
            created_run_ids durante el trabajo del usuario y cuente cada Run
            liquidado una sola vez. Cambiar task_id no convierte una repetición
            idempotente en un Run nuevo. Leer un resultado tiene cargo cero y
            listas de admisión vacías.
        result_url:
          type: string
          description: >-
            Ruta de URL autenticada y de solo lectura para consultar este
            resultado normalizado y el cargo total. Úsala con el origen de la
            API. No crea Runs ni reanuda el fallback. GET /v1/runs/:id sigue
            devolviendo el Run nativo e individual.
      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.