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

# Read an SEO research result

> Read normalized output, delivery status, and total charges for an existing SEO research request. Follow the result_url returned by the call.

Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still carry `result_status: pending` while a crawl runs; keep polling until `status` is terminal. This read creates no Runs, calls no Providers and does not resume fallback.


## OpenAPI

````yaml /openapi.json get /v1/solutions/gtm/seo_research/result
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/seo_research/result:
    get:
      tags:
        - Solutions
      summary: Read an SEO research result
      description: >-
        Follow result_url from an SEO research call to read normalized output,
        business result_status and the total charge of the same Runs. HTTP 200
        may still contain result_status=pending. This authenticated read creates
        no Runs, calls no Providers and does not resume fallback. GET
        /v1/runs/:id remains the native individual Run. The result context is
        signed, bound to the Workspace and checked against the current Key
        policy for every Run.
      operationId: gtm-seo-research-result
      parameters:
        - name: token
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 16384
            description: >-
              Opaque result context returned in result_url. Keep it unchanged
              and authenticate with a Key permitted to read every listed Run.
          required: true
      responses:
        '200':
          description: SeoResearchResult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeoResearchResult'
        '400':
          description: ValidationFailed
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
                  - $ref: '#/components/schemas/ValidationFailedEncoded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenEncoded'
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundEncoded'
        '429':
          description: RateLimited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedEncoded'
      security:
        - bearer: []
components:
  schemas:
    SeoResearchResult:
      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
        output:
          anyOf:
            - anyOf:
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          keyword:
                            anyOf:
                              - type: string
                              - type: 'null'
                          volume:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          cpc_usd:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          semrush_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          serpstat_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          dataforseo_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          ahrefs_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          intent:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - keyword
                          - volume
                          - cpc_usd
                          - semrush_keyword_difficulty
                          - serpstat_keyword_difficulty
                          - dataforseo_keyword_difficulty
                          - ahrefs_keyword_difficulty
                          - intent
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          position:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          domain:
                            anyOf:
                              - type: string
                              - type: 'null'
                          title:
                            anyOf:
                              - type: string
                              - type: 'null'
                          snippet:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - position
                          - url
                          - domain
                          - title
                          - snippet
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    organic_keywords:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    organic_traffic:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    organic_traffic_value_usd:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    paid_keywords:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    paid_traffic:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                  required:
                    - organic_keywords
                    - organic_traffic
                    - organic_traffic_value_usd
                    - paid_keywords
                    - paid_traffic
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          keyword:
                            anyOf:
                              - type: string
                              - type: 'null'
                          position:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          volume:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          cpc_usd:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          traffic:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                        required:
                          - keyword
                          - position
                          - url
                          - volume
                          - cpc_usd
                          - traffic
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          domain:
                            anyOf:
                              - type: string
                              - type: 'null'
                          common_keywords:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          organic_keywords:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          organic_traffic:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                        required:
                          - domain
                          - common_keywords
                          - organic_keywords
                          - organic_traffic
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    backlinks:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    referring_domains:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    semrush_authority_score:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    dataforseo_rank:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    serpstat_domain_rank:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    dofollow_backlinks:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    nofollow_backlinks:
                      anyOf:
                        - type: integer
                        - type: 'null'
                  required:
                    - backlinks
                    - referring_domains
                    - semrush_authority_score
                    - dataforseo_rank
                    - serpstat_domain_rank
                    - dofollow_backlinks
                    - nofollow_backlinks
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          source_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          target_url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          anchor:
                            anyOf:
                              - type: string
                              - type: 'null'
                          source_ahrefs_domain_rating:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          source_semrush_authority_score:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          source_dataforseo_rank:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          dofollow:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                          first_seen_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - source_url
                          - target_url
                          - anchor
                          - source_ahrefs_domain_rating
                          - source_semrush_authority_score
                          - source_dataforseo_rank
                          - dofollow
                          - first_seen_at
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          domain:
                            anyOf:
                              - type: string
                              - type: 'null'
                          ahrefs_domain_rating:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          semrush_authority_score:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          dataforseo_rank:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          backlinks:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          dofollow_backlinks:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          first_seen_at:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - domain
                          - ahrefs_domain_rating
                          - semrush_authority_score
                          - dataforseo_rank
                          - backlinks
                          - dofollow_backlinks
                          - first_seen_at
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    ahrefs_domain_rating:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                  required:
                    - ahrefs_domain_rating
                  additionalProperties: false
                - type: object
                  properties:
                    dataforseo_task_id:
                      anyOf:
                        - type: string
                        - type: 'null'
                    crawl_progress:
                      anyOf:
                        - type: string
                        - type: 'null'
                    crawl_stop_reason:
                      anyOf:
                        - type: string
                        - type: 'null'
                    pages_crawled:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    dataforseo_onpage_score:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    broken_links:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    non_indexable:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    duplicate_title:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    duplicate_description:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    duplicate_content:
                      anyOf:
                        - type: integer
                        - type: 'null'
                  required:
                    - dataforseo_task_id
                    - crawl_progress
                    - crawl_stop_reason
                    - pages_crawled
                    - dataforseo_onpage_score
                    - broken_links
                    - non_indexable
                    - duplicate_title
                    - duplicate_description
                    - duplicate_content
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          keyword:
                            anyOf:
                              - type: string
                              - type: 'null'
                          volume:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          cpc_usd:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          semrush_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          dataforseo_keyword_difficulty:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          positions:
                            type: object
                            additionalProperties:
                              anyOf:
                                - type: integer
                                - type: 'null'
                        required:
                          - keyword
                          - volume
                          - cpc_usd
                          - semrush_keyword_difficulty
                          - dataforseo_keyword_difficulty
                          - positions
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          domain:
                            anyOf:
                              - type: string
                              - type: 'null'
                          dataforseo_rank:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          backlinks_per_target:
                            type: object
                            additionalProperties:
                              anyOf:
                                - type: integer
                                - type: 'null'
                        required:
                          - domain
                          - dataforseo_rank
                          - backlinks_per_target
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    url:
                      anyOf:
                        - type: string
                        - type: 'null'
                    status_code:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    title:
                      anyOf:
                        - type: string
                        - type: 'null'
                    description:
                      anyOf:
                        - type: string
                        - type: 'null'
                    canonical:
                      anyOf:
                        - type: string
                        - type: 'null'
                    dataforseo_onpage_score:
                      anyOf:
                        - anyOf:
                            - type: number
                            - type: string
                              enum:
                                - Infinity
                                - '-Infinity'
                                - NaN
                        - type: 'null'
                    internal_links:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    external_links:
                      anyOf:
                        - type: integer
                        - type: 'null'
                  required:
                    - url
                    - status_code
                    - title
                    - description
                    - canonical
                    - dataforseo_onpage_score
                    - internal_links
                    - external_links
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          month:
                            anyOf:
                              - type: string
                              - type: 'null'
                          organic_keywords:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          organic_traffic:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          organic_traffic_value_usd:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                          paid_keywords:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          paid_traffic:
                            anyOf:
                              - anyOf:
                                  - type: number
                                  - type: string
                                    enum:
                                      - Infinity
                                      - '-Infinity'
                                      - NaN
                              - type: 'null'
                        required:
                          - month
                          - organic_keywords
                          - organic_traffic
                          - organic_traffic_value_usd
                          - paid_keywords
                          - paid_traffic
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          url:
                            anyOf:
                              - type: string
                              - type: 'null'
                          platform:
                            anyOf:
                              - type: string
                              - type: 'null'
                          mentions:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          ai_search_volume:
                            anyOf:
                              - type: integer
                              - type: 'null'
                          is_target_domain:
                            anyOf:
                              - type: boolean
                              - type: 'null'
                        required:
                          - url
                          - platform
                          - mentions
                          - ai_search_volume
                          - is_target_domain
                        additionalProperties: false
                  required:
                    - items
                  additionalProperties: false
                - type: object
                  properties:
                    ahrefs_ai_citations:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    ahrefs_ai_cited_pages:
                      anyOf:
                        - type: integer
                        - type: 'null'
                    ahrefs_ai_citations_by_platform:
                      anyOf:
                        - type: object
                          additionalProperties:
                            anyOf:
                              - type: integer
                              - type: 'null'
                        - type: 'null'
                    dataforseo_ai_mentions_by_platform:
                      anyOf:
                        - type: object
                          additionalProperties:
                            anyOf:
                              - type: integer
                              - type: 'null'
                        - type: 'null'
                    dataforseo_ai_search_volume_by_platform:
                      anyOf:
                        - type: object
                          additionalProperties:
                            anyOf:
                              - type: integer
                              - type: 'null'
                        - type: 'null'
                  required:
                    - ahrefs_ai_citations
                    - ahrefs_ai_cited_pages
                    - ahrefs_ai_citations_by_platform
                    - dataforseo_ai_mentions_by_platform
                    - dataforseo_ai_search_volume_by_platform
                  additionalProperties: false
            - type: 'null'
          description: >-
            Normalized fields per action. The Provider's native output is not
            repeated here; it stays on the Run (GET /v1/runs/:id). Values a
            Provider does not report are null. Money is USD. Authority scores
            keep the answering Provider's own metric and name and are never
            converted: ahrefs_domain_rating (Ahrefs Domain Rating, 0–100),
            semrush_authority_score (Semrush Authority Score, 0–100),
            dataforseo_rank (DataForSEO rank, 0–1000), serpstat_domain_rank
            (Serpstat Domain Rank, 0–100). Keyword difficulty is split the same
            way (semrush_keyword_difficulty, serpstat_keyword_difficulty,
            dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, each 0–100
            on its own model). Only the field of the Provider that answered is
            filled; the others are null. volume, traffic and cpc are the
            answering Provider's estimates; compare them only within one
            Provider (runs[].provider). An empty answer (result_status
            no_result) keeps the action's shape: items is [], or every field is
            null.


            - keyword_overview: items[]: keyword, volume, cpc_usd,
            semrush_keyword_difficulty, serpstat_keyword_difficulty,
            dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent

            - keyword_ideas: items[]: same row as keyword_overview

            - serp: items[]: position (organic position: 1 = first organic
            result; SERP features not counted), url, domain, title, snippet
            (organic results only)

            - domain_overview: organic_keywords, organic_traffic,
            organic_traffic_value_usd, paid_keywords, paid_traffic

            - ranked_keywords: items[]: keyword, position (organic position: 1 =
            first organic result; SERP features not counted), url, volume,
            cpc_usd, traffic

            - organic_competitors: items[]: domain, common_keywords,
            organic_keywords (the competitor's total), organic_traffic (the
            target domain and its subdomains are left out)

            - backlinks_overview: backlinks, referring_domains,
            semrush_authority_score, dataforseo_rank, serpstat_domain_rank,
            dofollow_backlinks, nofollow_backlinks

            - backlinks: items[]: source_url, target_url, anchor,
            source_ahrefs_domain_rating, source_semrush_authority_score,
            source_dataforseo_rank, dofollow, first_seen_at (ISO 8601 UTC;
            Semrush: zone not stated, no Z suffix). One row per link from every
            Provider

            - referring_domains: items[]: domain, ahrefs_domain_rating,
            semrush_authority_score, dataforseo_rank, backlinks,
            dofollow_backlinks, first_seen_at (ISO 8601 UTC; Semrush: zone not
            stated, no Z suffix)

            - domain_rating: ahrefs_domain_rating

            - site_audit: dataforseo_task_id (input to DataForSEO's OnPage
            report endpoints), crawl_progress, crawl_stop_reason (DataForSEO's
            vocabulary), pages_crawled, dataforseo_onpage_score, broken_links,
            non_indexable, duplicate_title, duplicate_description,
            duplicate_content

            - keyword_gap: items[]: keyword, volume, cpc_usd,
            semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions
            {domain: organic position; null = not in the top 100}, keyed by the
            domains sent. Semrush rows are keywords any of the domains ranks for
            (union); DataForSEO rows are keywords the competitor ranks for and
            you do not

            - backlink_gap: items[]: domain, dataforseo_rank,
            backlinks_per_target {competitor domain: count}

            - page_audit: url, status_code, title, description, canonical,
            dataforseo_onpage_score, internal_links, external_links

            - visibility_history: items[]: month, organic_keywords,
            organic_traffic, organic_traffic_value_usd, paid_keywords,
            paid_traffic

            - ai_citations: items[]: url, platform, mentions, ai_search_volume,
            is_target_domain (pages most cited in AI answers that mention the
            domain, from any site)

            - ai_visibility: ahrefs_ai_citations, ahrefs_ai_cited_pages,
            ahrefs_ai_citations_by_platform {platform: citations},
            dataforseo_ai_mentions_by_platform {platform: mentions},
            dataforseo_ai_search_volume_by_platform {platform: AI search
            volume}. Each Provider fills only its own fields; no cross-Provider
            total
        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: >-
            Total charge of runs in this Solution response. Null until all
            listed Runs settle. Each Run retains its own charge; 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.
        action:
          type: string
          enum:
            - keyword_overview
            - keyword_ideas
            - serp
            - domain_overview
            - ranked_keywords
            - organic_competitors
            - backlinks_overview
            - backlinks
            - referring_domains
            - domain_rating
            - site_audit
            - ai_visibility
            - keyword_gap
            - backlink_gap
            - page_audit
            - visibility_history
            - ai_citations
        result_status:
          type: string
          enum:
            - success
            - no_result
            - error
            - pending
          description: >-
            Business delivery status, independent of the final Run lifecycle in
            status. no_result is an empty but valid answer; error means the
            Provider output could not be delivered.
        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
              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
        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
    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
    ForbiddenEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    NotFoundEncoded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - not_found
            message:
              type: string
            reason:
              anyOf:
                - type: string
                - type: 'null'
            control:
              anyOf:
                - type: string
                - type: 'null'
            retry_after_ms:
              anyOf:
                - anyOf:
                    - type: integer
                    - type: 'null'
                - type: 'null'
            details:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - code
            - message
          additionalProperties: false
        request_id:
          type: string
      required:
        - error
        - request_id
      additionalProperties: false
    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
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer

````

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