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

> Runs a new lighthouse test.



## OpenAPI

````yaml api-reference/openapi.json post /v1/lighthouse-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-tests:
    post:
      tags:
        - Lighthouse Tests
      summary: Run a lighthouse test
      description: Runs a new lighthouse test.
      operationId: RunLighthouseTest
      requestBody:
        description: This is the lighthouse test body object
        content:
          application/json:
            schema:
              properties:
                url:
                  description: The url of webpage
                  type: string
                device:
                  $ref: '#/components/schemas/device_id'
                location:
                  $ref: '#/components/schemas/location_id'
                config:
                  $ref: '#/components/schemas/lighthouse_config'
            examples:
              default:
                $ref: '#/components/examples/run_lighthouse_test_request'
      responses:
        '201':
          description: A lighthouse report to be returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lighthouse_report'
              examples:
                default:
                  $ref: '#/components/examples/run_lighthouse_test_response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
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_report:
      type: object
      required:
        - url
        - device
        - location
        - status
        - lighthouse_version
      properties:
        id:
          type: string
        url:
          type: string
        device:
          $ref: '#/components/schemas/device_id'
        location:
          $ref: '#/components/schemas/location_id'
        config:
          $ref: '#/components/schemas/lighthouse_config'
        status:
          type: string
          enum:
            - idle
            - active
            - success
            - failed
        lighthouse_version:
          description: The version of the lighthouse used to generate the report
          type: string
        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'
        created_at:
          description: >-
            Time at which the test was created. Measured in seconds since the
            Unix epoch.
          type: number
        expires_at:
          description: >-
            Time at which the report will expire. Measured in seconds since the
            Unix epoch.
          type: number
        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: lt_LthsZedDcOUfYFHxN
        url: https://speedvitals.com
        device: macbookAirM1
        location: us
        config:
          http_version: '2'
          video: true
          adblock: true
        status: idle
        lighthouse_version: 9.6.2
        metrics:
          cumulative_layout_shift: 0
          first_contentful_paint: 515
          first_meaningful_paint: 566
          time_to_interactive: 725
          largest_contentful_paint: 515
          server_response_time: 21
          speed_index: 1123
          total_blocking_time: 69
          performance_score: 99
        report_url: https://speedvitals.com/report/speedvitals.com/Q6qWx6/
        created_at: 1657537268453
        expires_at: 1660129268453
        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_test_request:
      value:
        url: https://speedvitals.com
        device: macbookAirM1
        location: us
        config:
          connection: fiber
          video: true
          adblock: true
    run_lighthouse_test_response:
      value:
        url: https://speedvitals.com
        device: macbookAirM1
        location: us
        config:
          connection: fiber
          video: true
          adblock: true
        status: success
        lighthouse_version: 9.6.2
        metrics: null
        report_url: null
        created_at: 1657537268453
        expires_at: 1660129268453
        error: null
  responses:
    BadRequest:
      description: Invalid Request body or missing required parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    Unauthorized:
      description: Invalid API Key
    InsufficientCredits:
      description: Insufficient Credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    RateLimitExceeded:
      description: Rate Limit Exceeded
    InternalServerError:
      description: Internal Server Error
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````