> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a single topic-extraction run

> Returns the status and progress counters of one topic-extraction run. Use processed / totalSources for a progress bar.



## OpenAPI

````yaml https://api.mentionlab.io/api/docs-json get /api/v1/source-topics/runs/{runId}
openapi: 3.0.0
info:
  title: MentionLab Public API v0.3.4-rc
  description: ''
  version: 0.3.4-rc
  contact: {}
servers:
  - url: https://api.mentionlab.io
security: []
tags: []
paths:
  /api/v1/source-topics/runs/{runId}:
    get:
      tags:
        - Source Topics
      summary: Get a single topic-extraction run
      description: >-
        Returns the status and progress counters of one topic-extraction run.
        Use processed / totalSources for a progress bar.
      operationId: SourceTopicsV1Controller_getTopicRun_v1
      parameters:
        - name: runId
          required: true
          in: path
          description: UUID of the run to retrieve.
          schema:
            type: string
            format: uuid
        - name: x-project-id
          in: header
          description: Project ID to specify the project context
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceTopicRunResponse'
        '400':
          description: >-
            The request failed validation — the body, query or path parameters
            are malformed or out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: The request is missing valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: >-
            The authenticated principal lacks the required permission, or access
            to the requested organisation/project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    SourceTopicRunResponse:
      type: object
      properties:
        id:
          type: string
          description: Run UUID.
          example: 019dd32e-b19e-7956-88f6-4b9a877f3697
        status:
          description: Lifecycle status of the run.
          example: running
          allOf:
            - $ref: '#/components/schemas/SourceTopicRunStatus'
        totalSources:
          type: number
          description: Total sources (jobs) enqueued for this run.
          example: 100
        processed:
          type: number
          description: >-
            Sources processed so far (vectorized + skippedNoMeta +
            skippedPreMeta + failed). Use processed / totalSources for a
            progress bar.
          example: 64
        vectorized:
          type: number
          description: Sources whose metadata was embedded + stored.
          example: 41
        skippedNoMeta:
          type: number
          description: Sources skipped because no metadata sidecar was cached.
          example: 18
        skippedPreMeta:
          type: number
          description: Sources skipped because the snapshot predates metadata caching.
          example: 4
        failed:
          type: number
          description: Sources whose job failed terminally (retries exhausted).
          example: 1
        params:
          type: object
          description: Snapshot of the filters that produced this run.
          nullable: true
          example:
            startDate: '2026-06-01'
            countries:
              - US
        createdAt:
          type: string
          description: When the run was created.
          format: date-time
          example: '2026-06-25T13:35:29.000Z'
        updatedAt:
          type: string
          description: When the run last changed.
          format: date-time
          example: '2026-06-25T13:38:02.000Z'
        completedAt:
          type: string
          description: When the run finished (null while still running).
          format: date-time
          nullable: true
          example: '2026-06-25T13:40:11.000Z'
        topicsStatus:
          description: >-
            Topic-clustering lifecycle, independent of embedding `status`.
            `pending` while embedding; `clustering` once the topic job runs;
            `ready` when topics are available; `failed` on clustering error.
            Poll until `ready`, then GET /source-topics/runs/{runId}/topics.
          example: ready
          allOf:
            - $ref: '#/components/schemas/SourceTopicTopicsStatus'
        topicsCompletedAt:
          type: string
          description: When topic clustering finished (null until ready/failed).
          format: date-time
          nullable: true
          example: '2026-06-25T13:41:02.000Z'
      required:
        - id
        - status
        - totalSources
        - processed
        - vectorized
        - skippedNoMeta
        - skippedPreMeta
        - failed
        - params
        - createdAt
        - updatedAt
        - completedAt
        - topicsStatus
        - topicsCompletedAt
    ApiErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code of the error.
          example: 400
        message:
          type: string
          description: >-
            Human-readable description of the error. Validation failures return
            an array of per-field validation errors instead of a single string.
          example: Validation failed
        error:
          type: string
          description: Short name of the HTTP error.
          example: Bad Request
      required:
        - statusCode
    SourceTopicRunStatus:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
      description: Lifecycle status of the run.
    SourceTopicTopicsStatus:
      type: string
      enum:
        - pending
        - clustering
        - ready
        - failed
      description: >-
        Topic-clustering lifecycle, independent of embedding `status`. `pending`
        while embedding; `clustering` once the topic job runs; `ready` when
        topics are available; `failed` on clustering error. Poll until `ready`,
        then GET /source-topics/runs/{runId}/topics.

````