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

# List a job's executions

> `include` adds each execution's answer. Read it once the job is over.



## OpenAPI

````yaml https://api.mentionlab.io/api/docs/v2-json get /api/v2/projects/{projectId}/jobs/{jobId}/executions
openapi: 3.0.0
info:
  title: MentionLab Public API v2
  description: ''
  version: 0.6.48
  contact: {}
servers:
  - url: https://api.mentionlab.io
security: []
tags: []
paths:
  /api/v2/projects/{projectId}/jobs/{jobId}/executions:
    get:
      tags:
        - Jobs
      summary: List a job's executions
      description: '`include` adds each execution''s answer. Read it once the job is over.'
      operationId: JobExecutionsV2Controller_list_v2
      parameters:
        - name: jobId
          required: true
          in: path
          schema:
            type: string
        - name: page
          required: false
          in: query
          description: >-
            Which slice of the matched rows to return, counted from 1. Rows
            skipped are (page - 1) * limit.
          schema:
            minimum: 1
            maximum: 1000000
            default: 1
            example: 2
            type: integer
        - name: limit
          required: false
          in: query
          description: >-
            How many rows one page holds, capped at 100 to keep a single
            response bounded.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            example: 50
            type: integer
        - name: status
          required: false
          in: query
          description: Any of these; repeat the key or separate with commas
          schema:
            type: array
            items:
              type: string
              enum:
                - pending
                - success
                - failed
                - retrying
        - name: models
          required: false
          in: query
          description: Raw model names; repeat the key or separate with commas
          schema:
            example:
              - gpt-5-mini
              - claude-haiku-4-5
            type: array
            items:
              type: string
        - name: queryIds
          required: false
          in: query
          description: >-
            Executions of any of these queries, at most 100 ids; repeat the key
            or separate with commas
          schema:
            maxItems: 100
            example:
              - 018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42
            type: array
            items:
              type: string
              format: uuid
        - name: createdAfter
          required: false
          in: query
          description: >-
            Only executions created at or after this time; a job's executions
            share its launch time
          schema:
            format: date-time
            example: '2026-11-01T00:00:00.000Z'
            type: string
        - name: createdBefore
          required: false
          in: query
          description: Only executions created at or before this time
          schema:
            format: date-time
            example: '2026-11-30T23:59:59.999Z'
            type: string
        - name: sort
          required: false
          in: query
          description: >-
            Comma-separated field:asc|desc on createdAt, updatedAt, status or
            model. The default order is stable for paging; a sort on status or
            updatedAt is not
          schema:
            example: model:asc
            type: string
        - name: include
          required: false
          in: query
          description: >-
            Adds each execution's `answer` with these blocks; repeat the key or
            separate with commas. A page then holds at most 50 rows, and 25 when
            it holds text
          schema:
            example:
              - text
              - entities
            type: array
            items:
              type: string
              enum:
                - text
                - entities
                - citations
                - listings
                - ads
                - fan_outs
                - theme_mentions
        - name: x-project-id
          in: header
          description: Project ID to specify the project context
          required: true
          schema:
            type: string
        - name: projectId
          required: true
          in: path
          schema:
            format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PagingResponse'
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobExecutionV2Response'
                  page:
                    $ref: '#/components/schemas/Paging'
        '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'
        '404':
          description: No such job in the project
components:
  schemas:
    PagingResponse:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/Paging'
      required:
        - page
    JobExecutionV2Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the execution
        answerId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Id of the answer the execution produced; null until the execution
            has succeeded
        queryId:
          type: string
          format: uuid
          nullable: true
          description: Id of the query; null once the query is deleted
        queryText:
          type: string
          nullable: true
          description: The query's text, kept after the query is deleted
        model:
          type: string
          description: Raw model name
        executionNumber:
          type: integer
          description: >-
            Which repeat of this query on this model the execution is, counting
            from 1
        status:
          type: string
          enum:
            - pending
            - success
            - failed
            - retrying
          description: Where the execution as a whole stands
        states:
          description: How far each analysis of the execution got
          allOf:
            - $ref: '#/components/schemas/JobExecutionStatesV2'
        answer:
          nullable: true
          description: >-
            The answer with the asked blocks, sent with `include`; null while
            there is none to read
          type: object
          allOf:
            - $ref: '#/components/schemas/Answer'
        createdAt:
          type: string
          format: date-time
          description: When the job launch created the execution
        updatedAt:
          type: string
          format: date-time
          description: When the execution last changed state
      required:
        - id
        - answerId
        - queryId
        - queryText
        - model
        - executionNumber
        - status
        - states
        - createdAt
        - updatedAt
    Paging:
      type: object
      properties:
        totalRecords:
          type: number
        limit:
          type: number
        currentPage:
          type: number
        totalPages:
          type: number
        nextPage:
          type: number
        prevPage:
          type: number
      required:
        - totalRecords
        - limit
        - currentPage
        - totalPages
        - nextPage
        - prevPage
    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
    JobExecutionStatesV2:
      type: object
      properties:
        answer:
          type: string
          enum:
            - sent
            - done
            - retrying
            - failed
          nullable: true
          description: The answer analysis; null until it is sent
        shopping:
          type: string
          enum:
            - sent
            - done
            - retrying
            - failed
          nullable: true
          description: >-
            Extraction of the products and merchants the answer names; null
            until it is sent
        shoppingEnrichment:
          type: string
          enum:
            - sent
            - done
          nullable: true
          description: >-
            Enrichment of the listed products' brands, which runs beside the
            answer; null until it is sent
      required:
        - answer
        - shopping
        - shoppingEnrichment
    Answer:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the answer
        jobId:
          type: string
          format: uuid
          description: The job that ran it
        executionId:
          type: string
          format: uuid
          description: The execution it answers
        initiatedAt:
          type: string
          format: date-time
          description: When its job started, ISO 8601 UTC
          example: '2026-10-19T06:00:00.000Z'
        query:
          description: The query it answers
          allOf:
            - $ref: '#/components/schemas/AnswerQuery'
        responseTags:
          description: The response tags it carries, by name
          type: array
          items:
            $ref: '#/components/schemas/AnswerResponseTag'
        model:
          type: string
          description: The model name the job ran, as the models filter takes it
          example: scp-ml-chatgpt
        country:
          type: string
          nullable: true
          description: ISO 3166-1 alpha-2 country; null when unset
        language:
          type: string
          nullable: true
          description: ISO 639-1 language; null when unset
        hasSources:
          type: boolean
          description: The answer cites a source
        hasShopping:
          type: boolean
          description: The answer shows shopping results
        hasAds:
          type: boolean
          description: The answer shows ads
        noAnswerReason:
          type: string
          nullable: true
          description: Why the engine gave no answer; null when it answered
        analysed:
          nullable: true
          description: >-
            The analysed entity in this answer; null when the project analyses
            none
          type: object
          allOf:
            - $ref: '#/components/schemas/AnswerAnalysedEntity'
        isThemeAnalysed:
          type: boolean
          nullable: true
          description: >-
            Whether the theme analysis has processed the answer; null when the
            project runs none
        text:
          type: string
          nullable: true
          description: >-
            The answer, markdown; null when the engine gave none. With include
            'text'
        entities:
          description: Every entity it names, by position. With include 'entities'
          type: array
          items:
            $ref: '#/components/schemas/AnswerEntity'
        citations:
          description: Its citations, by position. With include 'citations'
          type: array
          items:
            $ref: '#/components/schemas/AnswerCitation'
        listings:
          description: Its listings, by position. With include 'listings'
          type: array
          items:
            $ref: '#/components/schemas/AnswerListing'
        ads:
          description: Its ads, by position. With include 'ads'
          type: array
          items:
            $ref: '#/components/schemas/AnswerAd'
        fanOuts:
          description: Its web searches, by phrase. With include 'fan_outs'
          type: array
          items:
            $ref: '#/components/schemas/AnswerFanOut'
        themeMentions:
          description: >-
            Its perception statements, by position. With include
            'theme_mentions'
          type: array
          items:
            $ref: '#/components/schemas/AnswerThemeMention'
      required:
        - id
        - jobId
        - executionId
        - initiatedAt
        - query
        - responseTags
        - model
        - country
        - language
        - hasSources
        - hasShopping
        - hasAds
        - noAnswerReason
        - analysed
        - isThemeAnalysed
    AnswerQuery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the query
        text:
          type: string
          nullable: true
          description: The query text sent to the engine; null once deleted
        type:
          type: string
          nullable: true
          description: The query type; null when untyped or deleted
        tags:
          description: The tags the query carries now, by name
          type: array
          items:
            $ref: '#/components/schemas/AnswerQueryTag'
      required:
        - id
        - text
        - type
        - tags
    AnswerResponseTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the response tag
        name:
          type: string
          description: Name of the tag
          example: Pricing
        groupId:
          type: string
          nullable: true
          format: uuid
          description: Id of the tag's group; null when the tag has no group
        groupName:
          type: string
          nullable: true
          description: Name of the tag's group; null when the tag has no group
          example: Topic
      required:
        - id
        - name
        - groupId
        - groupName
    AnswerAnalysedEntity:
      type: object
      properties:
        isMentioned:
          type: boolean
          description: The answer names the analysed entity
        position:
          type: number
          nullable: true
          description: Its mean rank in the answer, from 1; null when absent or unranked
        sentiment:
          type: number
          nullable: true
          description: >-
            Its sentiment in the answer, -1 to +1; null when no mention is
            scored
        stance:
          type: string
          nullable: true
          enum:
            - chosen
            - described
            - named
            - dismissed
            - criticized
          description: >-
            How the answer treats it, its strongest stance; null when it carries
            none
      required:
        - isMentioned
        - position
        - sentiment
        - stance
    AnswerEntity:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the entity, after merges
        name:
          type: string
          description: Name of the entity
        type:
          type: string
          nullable: true
          description: 'What the entity is: brand, person, company or other'
        isPrimary:
          type: boolean
          description: >-
            The project's own main entity; at most one entity per project holds
            it
        isOwned:
          type: boolean
          description: An entity the project owns
        isCompetitor:
          type: boolean
          description: Tracked as a competitor of the project
        position:
          type: number
          nullable: true
          description: Its mean rank in the answer, from 1; null when unranked
        sentiment:
          type: number
          nullable: true
          description: >-
            Its sentiment in the answer, -1 to +1; null when no mention is
            scored
        stance:
          type: string
          nullable: true
          enum:
            - chosen
            - described
            - named
            - dismissed
            - criticized
          description: >-
            How the answer treats it, its strongest stance; null when it carries
            none
        mentionCount:
          type: number
          description: Its mentions in the answer
      required:
        - id
        - name
        - type
        - isPrimary
        - isOwned
        - isCompetitor
        - position
        - sentiment
        - stance
        - mentionCount
    AnswerCitation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the citation
        url:
          type: string
          description: The cited page, as cited
        domain:
          type: string
          nullable: true
          description: The cited domain, registrable form
        title:
          type: string
          nullable: true
          description: Title of the page; null when unknown
        position:
          type: number
          nullable: true
          description: Its place among the citations, from 1; null when unknown
      required:
        - id
        - url
        - domain
        - title
        - position
    AnswerListing:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the listing
        productId:
          type: string
          nullable: true
          format: uuid
          description: The product of the catalogue, after merges; null when none
        entityId:
          type: string
          nullable: true
          format: uuid
          description: The entity that makes it, after merges; null when none
        entityName:
          type: string
          nullable: true
          description: Name of that entity
        name:
          type: string
          description: Name of the product, else the name the answer shows
        rawName:
          type: string
          nullable: true
          description: The name the answer shows, as the engine gave it
        externalId:
          type: string
          nullable: true
          description: The engine's own id of the product
        position:
          type: number
          description: Its place among the listings, from 1
        imageUrl:
          type: string
          nullable: true
          description: Image the answer shows
        price:
          type: number
          nullable: true
          description: Price shown, in priceCurrency
        priceCurrency:
          type: string
          nullable: true
          description: ISO 4217 currency of price
        starRating:
          type: number
          nullable: true
          description: Star rating shown
        reviewCount:
          type: number
          nullable: true
          description: Review count shown
        offers:
          description: The offers, by position
          type: array
          items:
            $ref: '#/components/schemas/AnswerOffer'
      required:
        - id
        - productId
        - entityId
        - entityName
        - name
        - rawName
        - externalId
        - position
        - imageUrl
        - price
        - priceCurrency
        - starRating
        - reviewCount
        - offers
    AnswerAd:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the ad
        position:
          type: number
          description: Its place among the ads, from 1
        format:
          type: string
          nullable: true
          description: The ad format the engine names
        advertiser:
          type: string
          nullable: true
          description: Who paid for the ad
        entityId:
          type: string
          nullable: true
          format: uuid
          description: The entity advertised, after merges; null when none
        entityName:
          type: string
          nullable: true
          description: Name of that entity
        title:
          type: string
          nullable: true
          description: Ad title
        body:
          type: string
          nullable: true
          description: Ad text
        imageUrl:
          type: string
          nullable: true
          description: Image of the ad; null when not captured
        url:
          type: string
          nullable: true
          description: Where the ad links
        price:
          type: number
          nullable: true
          description: Price shown, in priceCurrency
        priceCurrency:
          type: string
          nullable: true
          description: ISO 4217 currency of price
        strikethroughPrice:
          type: number
          nullable: true
          description: Struck-through price shown, in its currency
        strikethroughPriceCurrency:
          type: string
          nullable: true
          description: ISO 4217 currency of strikethroughPrice
        starRating:
          type: number
          nullable: true
          description: Star rating shown
      required:
        - id
        - position
        - format
        - advertiser
        - entityId
        - entityName
        - title
        - body
        - imageUrl
        - url
        - price
        - priceCurrency
        - strikethroughPrice
        - strikethroughPriceCurrency
        - starRating
    AnswerFanOut:
      type: object
      properties:
        id:
          type: string
          description: 'Id of the search: its phrase''s sha256, hex'
          example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        phrase:
          type: string
          description: The phrase the engine searched
      required:
        - id
        - phrase
    AnswerThemeMention:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of the statement
        entityId:
          type: string
          nullable: true
          format: uuid
          description: >-
            The entity it is about, after merges; null when it is about the
            subject
        entityName:
          type: string
          nullable: true
          description: Name of that entity
        phrase:
          type: string
          description: What the answer says, in a few words
          example: soft cushioning
        quote:
          type: string
          nullable: true
          description: The words of the answer it rests on, verbatim
        tone:
          type: string
          enum:
            - positive
            - neutral
            - negative
            - mixed
          nullable: true
          description: How the statement reads; null when not judged
          example: positive
        sentiment:
          type: number
          nullable: true
          description: Its sentiment, -1 to +1; null when not scored
        role:
          type: string
          enum:
            - central
            - supporting
            - peripheral
          nullable: true
          description: How much the answer leans on it; null when not judged
          example: central
        position:
          type: integer
          nullable: true
          description: Its place among the answer's statements, from 1; null when unknown
      required:
        - id
        - entityId
        - entityName
        - phrase
        - quote
        - tone
        - sentiment
        - role
        - position
    AnswerQueryTag:
      type: object
      properties:
        id:
          type: number
          description: Id of the query tag
          example: 12
        name:
          type: string
          description: Name of the tag
          example: Branded
        groupId:
          type: string
          nullable: true
          format: uuid
          description: Id of the tag's group; null when the tag has no group
        groupName:
          type: string
          nullable: true
          description: Name of the tag's group; null when the tag has no group
          example: Intent
      required:
        - id
        - name
        - groupId
        - groupName
    AnswerOffer:
      type: object
      properties:
        merchantName:
          type: string
          description: Name of the merchant
        rawMerchantName:
          type: string
          nullable: true
          description: >-
            The merchant's name as the AI engine showed it on this offer; null
            for offers stored before this field existed
        merchantDomain:
          type: string
          nullable: true
          description: Domain of the merchant
        url:
          type: string
          description: Link to the offer
        price:
          type: number
          nullable: true
          description: Price of the offer, in priceCurrency
        priceCurrency:
          type: string
          nullable: true
          description: ISO 4217 currency of price and shippingPrice
        position:
          type: number
          nullable: true
          description: Its place among the offers, from 1; null when unknown
        isAboveFold:
          type: boolean
          nullable: true
          description: Shown without expanding the offers; null when unknown
        shippingPrice:
          type: number
          nullable: true
          description: Shipping cost, 0 when free; null when unknown
        isInStock:
          type: boolean
          nullable: true
          description: The offer reads as in stock; null when unknown
        details:
          type: string
          nullable: true
          description: Stock and delivery text as the engine shows it
      required:
        - merchantName
        - rawMerchantName
        - merchantDomain
        - url
        - price
        - priceCurrency
        - position
        - isAboveFold
        - shippingPrice
        - isInStock
        - details

````

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