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

# Run a lighthouse batch test

> Runs a new lighthouse batch test.



## OpenAPI

````yaml api-reference/openapi.json post /v1/lighthouse-batch-tests
openapi: 3.1.0
info:
  contact:
    email: contact@speedvitals.com
    name: SpeedVitals Dev Team
    url: https://speedvitals.com
  description: >
    The SpeedVitals REST API. Please see
    [https://docs.speedvitals.com/api](https://docs.speedvitals.com/api/) for
    more details.
  termsOfService: https://speedvitals.com/terms-of-use
  title: SpeedVitals API
  version: 0.1.0
servers:
  - url: https://api.speedvitals.com
security:
  - apiKey: []
tags:
  - name: Ping
  - name: Devices
  - name: Locations
  - name: Lighthouse Tests
  - name: Lighthouse Batch Tests
  - name: TTFB Regions
  - name: TTFB Tests
  - name: Account
externalDocs:
  description: Home
  url: https://speedvitals.com
paths:
  /v1/lighthouse-batch-tests:
    post:
      tags:
        - Lighthouse Batch Tests
      summary: Run a lighthouse batch test
      description: Runs a new lighthouse batch test.
      operationId: RunLighthouseBatchTest
      requestBody:
        description: This is the lighthouse batch test body object
        content:
          application/json:
            schema:
              properties:
                urls:
                  title: list of urls
                  description: >-
                    For multiple-urls batch type, provide an array of urls to
                    test. For other batch types, provide a single url in array
                    and if multiple urls are provided, only first in the list
                    will be used for the test. All invalid urls in the array
                    will be ignored.
                  type: array
                  items:
                    maxLength: 5000
                    type: string
                devices:
                  title: list of devices
                  description: >-
                    For multiple-devices batch type, provide an array of device
                    ids to test or leave it empty for testing on all preset
                    devices. For other batch types, provide a single device id
                    in array and if multiple device ids are provided, only first
                    in the list will be used for the test. All invalid device
                    ids in the array will be ignored.
                  type: array
                  items:
                    $ref: '#/components/schemas/device_id'
                    maxLength: 5000
                locations:
                  title: list of locations
                  description: >-
                    For multiple-locations batch type, provide an array of
                    location ids to test or leave it empty for testing on all
                    preset locations. For other batch types, provide just a
                    single location id in array and if multiple location ids are
                    provided, only first in the list will be used for the test.
                    All invalid location ids in the array will be ignored.
                  type: array
                  items:
                    $ref: '#/components/schemas/location_id'
                    maxLength: 5000
                batch_type:
                  description: The type of batch test to run
                  type: string
                  enum:
                    - multiple-urls
                    - multiple-devices
                    - multiple-locations
                config:
                  $ref: '#/components/schemas/lighthouse_config'
            examples:
              default:
                $ref: '#/components/examples/run_lighthouse_batch_test_request'
      responses:
        '201':
          description: A lighthouse batch report to be returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lighthouse_batch_report'
              examples:
                default:
                  $ref: '#/components/examples/run_lighthouse_batch_test_response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
components:
  schemas:
    device_id:
      type: string
      example: macbookAirM1
      enum:
        - mobile
        - desktop
        - macbookAirM1
        - highEndLaptop
        - ipad102
        - galaxyTabS7
        - iphone13ProMax
        - iphone11
        - galaxyS10Plus
        - redmiNote8Pro
        - iphone7
        - galaxyA50
        - galaxyJ8
        - motoG5
        - redmi5A
    location_id:
      type: string
      example: us
      enum:
        - us
        - ca
        - br
        - de
        - uk
        - nl
        - pl
        - ch
        - jp
        - in
        - sg
        - au
        - id
        - kr
        - tw
    lighthouse_config:
      type: object
      properties:
        connection:
          description: Connection Type
          type:
            - string
            - 'null'
          enum:
            - fiber
            - cable
            - dsl
            - 5g
            - wifi_fast
            - wifi
            - 4g_fast
            - 4g
            - 3g_fast
            - 3g
            - 3g_slow
            - 2g_edge
            - 2g
            - null
          maxLength: 5000
        throttling_method:
          description: Choose between simulated throttling and applied throttling
          type:
            - string
            - 'null'
          maxLength: 5000
          default: simulated
        http_version:
          description: Force HTTP/1.1 or HTTP/2(default)
          type:
            - string
            - 'null'
          maxLength: 5000
          default: '2'
        video:
          description: Enable page load video
          type:
            - boolean
            - 'null'
          maxLength: 5000
          default: false
        adblock:
          description: Enable Adblock
          type:
            - boolean
            - 'null'
          default: false
        user_agent:
          description: Run test with custom user agent
          type:
            - string
            - 'null'
          maxLength: 5000
        auth_username:
          description: Username for authentication
          type:
            - string
            - 'null'
          maxLength: 5000
        auth_password:
          description: Password for authentication
          type:
            - string
            - 'null'
          maxLength: 5000
        cookies:
          description: List of session cookies
          type:
            - array
            - 'null'
          items:
            type: string
          maxLength: 5000
        whitelist:
          description: List of whitelisted urls(Max 5)
          type:
            - array
            - 'null'
          items:
            type: string
        blacklist:
          description: List of blacklisted urls(Max 10)
          type:
            - array
            - 'null'
          items:
            type: string
    lighthouse_batch_report:
      type: object
      required:
        - urls
        - devices
        - locations
        - batch_type
      properties:
        id:
          type: string
        urls:
          type: array
          items:
            type: string
        devices:
          type: array
          items:
            $ref: '#/components/schemas/device_id'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/location_id'
        batch_type:
          type: string
          enum:
            - multiple-urls
            - multiple-devices
            - multiple-locations
        config:
          $ref: '#/components/schemas/lighthouse_config'
        status:
          type: string
          enum:
            - idle
            - active
            - completed
        lighthouse_version:
          description: The version of the lighthouse used to run the tests
          type: string
        report_url:
          type: string
        created_at:
          description: >-
            Time at which the batch test was created. Measured in seconds since
            the Unix epoch.
          type: number
        expires_at:
          description: >-
            Time at which the batch report will expire. Measured in seconds
            since the Unix epoch.
          type: number
        reports:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              url:
                type: string
              device:
                $ref: '#/components/schemas/device_id'
              location:
                $ref: '#/components/schemas/location_id'
              status:
                type: string
                enum:
                  - idle
                  - active
                  - success
                  - failed
              metrics:
                $ref: '#/components/schemas/lighthouse_metrics'
              report_url:
                description: >-
                  The URL at which SpeedVitals report is accessible (Present
                  when status is success)
                type:
                  - string
                  - 'null'
              error:
                description: >-
                  Contains error code and description(present only if status is
                  failed)
                type:
                  - object
                  - 'null'
                properties:
                  code:
                    description: Error code specific to lighthouse error
                    type: string
                  message:
                    description: Error message describing the summary of lighthouse error
                    type: string
      example:
        id: lbt_IU8rN0XQmIWEqGkP
        urls:
          - https://speedvitals.com
          - https://blog.speedvitals.com
        devices:
          - macbookAirM1
        locations:
          - us
        batch_type: multiple-urls
        status: active
        lighthouse_version: 9.6.2
        report_url: https://speedvitals.com/result/afd98w0l/
        created_at: 1657539924734
        expires_at: 1660131924733
        reports:
          - id: lt_dObdG5EW4d231hto
            url: https://speedvitals.com
            device: macbookAirM1
            location: us
            status: success
            metrics:
              cumulative_layout_shift: 0
              first_contentful_paint: 292
              first_meaningful_paint: 297
              time_to_interactive: 297
              largest_contentful_paint: 434
              server_response_time: 32
              speed_index: 900
              total_blocking_time: 0
              performance_score: 100
            report_url: https://speedvitals.com/report/speedvitals.com/IvWenx/
            error: null
          - id: lt_dmpbeQ2xk1XPh4UP
            url: https://blog.speedvitals.com
            device: macbookAirM1
            location: us
            status: idle
            metrics:
              cumulative_layout_shift: 0
              first_contentful_paint: 322
              first_meaningful_paint: 365
              time_to_interactive: 368
              largest_contentful_paint: 488
              server_response_time: 68
              speed_index: 1406
              total_blocking_time: 0
              performance_score: 99
            report_url: https://speedvitals.com/report/blog.speedvitals.com/3t4lm7
            error: null
    lighthouse_metrics:
      type:
        - object
        - 'null'
      properties:
        cumulative_layout_shift:
          description: Cumulative Layout Shift
          type: number
          example: 0.01
        first_contentful_paint:
          type: number
          description: First Contentful Paint time (in milliseconds)
          example: 1232
        first_meaningful_paint:
          description: First Meaningful Paint time (in milliseconds)
          type: number
          example: 1245
        time_to_interactive:
          description: Time to Interactive (in milliseconds)
          type: number
          example: 1458
        largest_contentful_paint:
          description: Largest Contentful Paint time (in milliseconds)
          type: number
          example: 1245
        server_response_time:
          description: TTFB (in milliseconds)
          type: number
          example: 70
        speed_index:
          description: Speed Index (in milliseconds)
          type: number
          example: 1367
        total_blocking_time:
          description: Total Blocking time (in milliseconds)
          type: number
          example: 39
        performance_score:
          description: Performance Score (in percentage)
          type: number
          example: 96
    error:
      description: An error response from the SpeedVitals API
      type: object
      properties:
        code:
          description: An error code specific to the error.
          type: string
        message:
          description: A human-readable message providing more details about the error.
          type: string
  examples:
    run_lighthouse_batch_test_request:
      value:
        urls:
          - https://speedvitals.com
          - https://blog.speedvitals.com
        devices:
          - macbookAirM1
        locations:
          - us
        batch_type: multiple-urls
    run_lighthouse_batch_test_response:
      value:
        id: lbt_IU8rN0XQmIWEqGkP
        urls:
          - https://speedvitals.com
          - https://blog.speedvitals.com
        devices:
          - macbookAirM1
        locations:
          - us
        batch_type: multiple-urls
        status: idle
        lighthouse_version: 9.6.2
        report_url: https://speedvitals.com/result/afd98w0l/
        created_at: 1657539924734
        expires_at: 1660131924733
        reports:
          - id: lt_dObdG5EW4d231hto
            url: https://speedvitals.com
            device: macbookAirM1
            location: us
            status: success
            metrics:
              cumulative_layout_shift: 0
              first_contentful_paint: 292
              first_meaningful_paint: 297
              time_to_interactive: 297
              largest_contentful_paint: 434
              server_response_time: 32
              speed_index: 900
              total_blocking_time: 0
              performance_score: 100
            report_url: https://speedvitals.com/report/speedvitals.com/IvWenx/
            error: null
          - id: lt_dmpbeQ2xk1XPh4UP
            url: https://blog.speedvitals.com
            device: macbookAirM1
            location: us
            status: idle
            metrics:
              cumulative_layout_shift: 0
              first_contentful_paint: 322
              first_meaningful_paint: 365
              time_to_interactive: 368
              largest_contentful_paint: 488
              server_response_time: 68
              speed_index: 1406
              total_blocking_time: 0
              performance_score: 99
            report_url: https://speedvitals.com/report/blog.speedvitals.com/3t4lm7
            error: null
  responses:
    BadRequest:
      description: Invalid Request body or missing required parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    InsufficientCredits:
      description: Insufficient Credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````