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

# The signed-in supplier’s Search insights

> Shown, Seen, profile opens, open rate, bookings from search, average position, missed searches by reason and the channel / service / area / time-asked breakdowns, each with the previous equal-length period and a daily series — the dashboard’s Search insights tab. `?days=7|28|90` (default 28) or `?from=YYYY-MM-DD&to=YYYY-MM-DD` (at most 365 days), dates in the supplier’s home zone. `nothing_yet` when no counted search involved the supplier in either window. Requires the API key and the supplier’s user token. 403 `INSIGHTS_DISABLED` when the project’s Search insights switch is off.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/search-insights
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/suppliers/me/search-insights:
    get:
      tags:
        - Supplier plane
      summary: The signed-in supplier’s Search insights
      description: >-
        Shown, Seen, profile opens, open rate, bookings from search, average
        position, missed searches by reason and the channel / service / area /
        time-asked breakdowns, each with the previous equal-length period and a
        daily series — the dashboard’s Search insights tab. `?days=7|28|90`
        (default 28) or `?from=YYYY-MM-DD&to=YYYY-MM-DD` (at most 365 days),
        dates in the supplier’s home zone. `nothing_yet` when no counted search
        involved the supplier in either window. Requires the API key and the
        supplier’s user token. 403 `INSIGHTS_DISABLED` when the project’s Search
        insights switch is off.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            enum:
              - '7'
              - '28'
              - '90'
            description: A trailing window of whole days ending today in your home zone
          required: false
          description: A trailing window of whole days ending today in your home zone
          name: days
          in: query
        - schema:
            type: string
            description: First day of a custom range, YYYY-MM-DD in your home zone
          required: false
          description: First day of a custom range, YYYY-MM-DD in your home zone
          name: from
          in: query
        - schema:
            type: string
            description: Last day of a custom range (inclusive), YYYY-MM-DD
          required: false
          description: Last day of a custom range (inclusive), YYYY-MM-DD
          name: to
          in: query
      responses:
        '200':
          description: The search insights
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                          - ok
                          - nothing_yet
                      window:
                        type: object
                        properties:
                          preset:
                            anyOf:
                              - type: number
                                enum:
                                  - 7
                              - type: number
                                enum:
                                  - 28
                              - type: number
                                enum:
                                  - 90
                              - nullable: true
                          from:
                            type: string
                          to:
                            type: string
                          days:
                            type: integer
                            minimum: 1
                            maximum: 365
                          zone:
                            type: string
                            minLength: 1
                        required:
                          - preset
                          - from
                          - to
                          - days
                          - zone
                        additionalProperties: false
                      previous:
                        type: object
                        properties:
                          from:
                            type: string
                          to:
                            type: string
                          days:
                            type: integer
                            minimum: 1
                            maximum: 365
                        required:
                          - from
                          - to
                          - days
                        additionalProperties: false
                      tiles:
                        type: object
                        nullable: true
                        properties:
                          shown:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                          seen:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                          opens:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                          openRate:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                          bookings:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                          position:
                            type: object
                            properties:
                              value:
                                type: number
                                nullable: true
                              previous:
                                type: number
                                nullable: true
                              delta:
                                type: number
                                nullable: true
                              series:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                              previousSeries:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    date:
                                      type: string
                                    value:
                                      type: number
                                      nullable: true
                                  required:
                                    - date
                                    - value
                                  additionalProperties: false
                            required:
                              - value
                              - previous
                              - delta
                              - series
                              - previousSeries
                            additionalProperties: false
                        required:
                          - shown
                          - seen
                          - opens
                          - openRate
                          - bookings
                          - position
                        additionalProperties: false
                      seenReporting:
                        type: object
                        nullable: true
                        properties:
                          reporting:
                            type: integer
                            minimum: 0
                          total:
                            type: integer
                            minimum: 0
                        required:
                          - reporting
                          - total
                        additionalProperties: false
                      missed:
                        type: object
                        nullable: true
                        properties:
                          total:
                            type: integer
                            minimum: 0
                          byReason:
                            type: array
                            items:
                              type: object
                              properties:
                                reason:
                                  type: string
                                  enum:
                                    - NOT_FREE
                                    - NO_SERVICE
                                    - OUTSIDE_TRAVEL
                                count:
                                  type: integer
                                  minimum: 0
                                share:
                                  type: number
                                  minimum: 0
                                  maximum: 1
                                detail:
                                  oneOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - asked_time
                                        grid:
                                          type: array
                                          items:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                level:
                                                  type: integer
                                                  minimum: 0
                                                  maximum: 5
                                                count:
                                                  anyOf:
                                                    - type: integer
                                                      minimum: 0
                                                    - type: string
                                                      enum:
                                                        - few
                                              required:
                                                - level
                                                - count
                                              additionalProperties: false
                                          description: >-
                                            [day MON…SUN][hour 6 AM…9 PM] in
                                            window.zone
                                        ranges:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              day:
                                                type: string
                                                enum:
                                                  - MON
                                                  - TUE
                                                  - WED
                                                  - THU
                                                  - FRI
                                                  - SAT
                                                  - SUN
                                              start:
                                                type: string
                                                pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                              end:
                                                type: string
                                                pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                                description: Exclusive end, HH:MM local
                                              count:
                                                type: integer
                                                minimum: 0
                                              level:
                                                type: integer
                                                minimum: 1
                                                maximum: 5
                                            required:
                                              - day
                                              - start
                                              - end
                                              - count
                                              - level
                                            additionalProperties: false
                                      required:
                                        - kind
                                        - grid
                                        - ranges
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - services
                                        items:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              key:
                                                type: string
                                                minLength: 1
                                              label:
                                                type: string
                                                minLength: 1
                                              count:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - key
                                              - label
                                              - count
                                            additionalProperties: false
                                      required:
                                        - kind
                                        - items
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - distance
                                        bands:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              fromKm:
                                                type: integer
                                                minimum: 0
                                              toKm:
                                                type: integer
                                                minimum: 0
                                              count:
                                                type: integer
                                                minimum: 0
                                            required:
                                              - fromKm
                                              - toKm
                                              - count
                                            additionalProperties: false
                                      required:
                                        - kind
                                        - bands
                                      additionalProperties: false
                              required:
                                - reason
                                - count
                                - share
                                - detail
                              additionalProperties: false
                        required:
                          - total
                          - byReason
                        additionalProperties: false
                      breakdowns:
                        type: object
                        nullable: true
                        properties:
                          channel:
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  minLength: 1
                                label:
                                  type: string
                                  minLength: 1
                                shown:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                seen:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                opens:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                openRate:
                                  type: number
                                  nullable: true
                                  minimum: 0
                                  maximum: 1
                                missed:
                                  type: integer
                                  minimum: 0
                                note:
                                  type: string
                                  minLength: 1
                              required:
                                - key
                                - label
                                - shown
                                - seen
                                - opens
                                - openRate
                              additionalProperties: false
                          service:
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  minLength: 1
                                label:
                                  type: string
                                  minLength: 1
                                shown:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                seen:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                opens:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                openRate:
                                  type: number
                                  nullable: true
                                  minimum: 0
                                  maximum: 1
                                missed:
                                  type: integer
                                  minimum: 0
                                note:
                                  type: string
                                  minLength: 1
                              required:
                                - key
                                - label
                                - shown
                                - seen
                                - opens
                                - openRate
                              additionalProperties: false
                          area:
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  minLength: 1
                                label:
                                  type: string
                                  minLength: 1
                                shown:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                seen:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                opens:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                openRate:
                                  type: number
                                  nullable: true
                                  minimum: 0
                                  maximum: 1
                                missed:
                                  type: integer
                                  minimum: 0
                                note:
                                  type: string
                                  minLength: 1
                              required:
                                - key
                                - label
                                - shown
                                - seen
                                - opens
                                - openRate
                              additionalProperties: false
                          timeAsked:
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  minLength: 1
                                label:
                                  type: string
                                  minLength: 1
                                shown:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                seen:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                opens:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                openRate:
                                  type: number
                                  nullable: true
                                  minimum: 0
                                  maximum: 1
                                missed:
                                  type: integer
                                  minimum: 0
                                note:
                                  type: string
                                  minLength: 1
                              required:
                                - key
                                - label
                                - shown
                                - seen
                                - opens
                                - openRate
                              additionalProperties: false
                        required:
                          - channel
                          - service
                          - area
                          - timeAsked
                        additionalProperties: false
                      suggestions:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                key:
                                  type: string
                                  pattern: >-
                                    ^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$
                                day:
                                  type: string
                                  enum:
                                    - MON
                                    - TUE
                                    - WED
                                    - THU
                                    - FRI
                                    - SAT
                                    - SUN
                                start:
                                  type: string
                                  pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                  description: Local wall clock, HH:MM, in window.zone
                                end:
                                  type: string
                                  pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                  description: Exclusive end, HH:MM local
                                booked:
                                  type: integer
                                  minimum: 0
                                kind:
                                  type: string
                                  enum:
                                    - open
                                unfilled:
                                  type: integer
                                  minimum: 0
                                prefill:
                                  type: object
                                  properties:
                                    weeklyTimeRanges:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          dayOfWeek:
                                            type: string
                                            enum:
                                              - MO
                                              - TU
                                              - WE
                                              - TH
                                              - FR
                                              - SA
                                              - SU
                                            description: >-
                                              The weekday this range falls on, in the
                                              row’s zone.
                                            example: MO
                                          startTime:
                                            type: string
                                            pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                            description: >-
                                              Wall-clock start, HH:MM in the row’s
                                              zone.
                                            example: '09:00'
                                          endTime:
                                            type: string
                                            pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                            description: >-
                                              Wall-clock end, HH:MM in the row’s zone;
                                              must differ from startTime.
                                            example: '17:00'
                                          crossesMidnight:
                                            type: boolean
                                            description: >-
                                              True exactly when endTime is earlier
                                              than startTime (the range ends next
                                              day).
                                            example: false
                                          sortOrder:
                                            type: integer
                                            minimum: 0
                                            description: >-
                                              Display order among the ranges of one
                                              day, from 0.
                                            example: 0
                                        required:
                                          - dayOfWeek
                                          - startTime
                                          - endTime
                                          - crossesMidnight
                                          - sortOrder
                                      minItems: 1
                                  required:
                                    - weeklyTimeRanges
                                  additionalProperties: false
                              required:
                                - key
                                - day
                                - start
                                - end
                                - booked
                                - kind
                                - unfilled
                                - prefill
                              additionalProperties: false
                            - type: object
                              properties:
                                key:
                                  type: string
                                  pattern: >-
                                    ^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$
                                day:
                                  type: string
                                  enum:
                                    - MON
                                    - TUE
                                    - WED
                                    - THU
                                    - FRI
                                    - SAT
                                    - SUN
                                start:
                                  type: string
                                  pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                  description: Local wall clock, HH:MM, in window.zone
                                end:
                                  type: string
                                  pattern: ^([01]\d|2[0-3]):[0-5]\d$
                                  description: Exclusive end, HH:MM local
                                booked:
                                  type: integer
                                  minimum: 0
                                kind:
                                  type: string
                                  enum:
                                    - quiet
                                scheduleId:
                                  type: string
                                  minLength: 1
                              required:
                                - key
                                - day
                                - start
                                - end
                                - booked
                                - kind
                                - scheduleId
                              additionalProperties: false
                      asOf:
                        type: string
                        nullable: true
                        format: date-time
                      complete:
                        type: boolean
                    required:
                      - state
                      - window
                      - previous
                      - tiles
                      - seenReporting
                      - missed
                      - breakdowns
                      - suggestions
                      - asOf
                      - complete
                    additionalProperties: false
                required:
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Missing or invalid API key or user token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: >-
            The API key cannot access this project (FORBIDDEN) or lacks standard
            API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no
            MarketBox account record (FORBIDDEN, "User account not found.
            Complete registration first."); or the signed-in user is not a
            member of the project (NOT_A_MEMBER), their membership has ended
            (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s
            permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they
            do not hold (ACTING_ROLE_NOT_HELD); or INSIGHTS_DISABLED (the
            project turned the feature off)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: >-
            The signed-in user has no supplier record here: no SUPPLIER among
            the roles they act under (NO_SUPPLIER_ROLE), or no single supplier
            record linked to them (SUPPLIER_NOT_LINKED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - ApiKeyAuth: []
          EndUserBearer: []
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.
    EndUserBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The signed-in person's Cognito access token, issued to this
        application's app client. Sent with the API key on the /clients/me and
        /suppliers/me routes.

````

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