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

> Runs a new TTFB test for a region.



## OpenAPI

````yaml api-reference/openapi.json post /v1/ttfb-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/ttfb-tests:
    post:
      tags:
        - TTFB Tests
      summary: Run a TTFB test
      description: Runs a new TTFB test for a region.
      operationId: RunTTFBTest
      requestBody:
        description: This is the TTFB test body object
        content:
          application/json:
            schema:
              properties:
                url:
                  description: The url of the webpage
                  type: string
                  example: https://speedvitals.com
                region:
                  $ref: '#/components/schemas/ttfb_region_id'
                  description: The id of a ttfb region
                  example: asia
      responses:
        '201':
          description: A TTFB result to be returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ttfb_result'
              examples:
                default:
                  $ref: '#/components/examples/ttfb_result'
        '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:
    ttfb_region_id:
      type: string
      example: asia
      enum:
        - asia
        - america
        - europe
    ttfb_result:
      type: object
      required:
        - url
        - region
      properties:
        url:
          type: string
        region:
          $ref: '#/components/schemas/ttfb_region_id'
        result:
          type: array
          items:
            type: object
            properties:
              location_id:
                type: string
              location_name:
                type: string
              status:
                type: string
                enum:
                  - success
                  - failed
              data:
                type:
                  - object
                  - 'null'
                properties:
                  timings:
                    type: object
                    properties:
                      dns_lookup:
                        description: DNS Lookup time (in milliseconds)
                        type: integer
                      server_processing:
                        description: Server Processing time (in milliseconds)
                        type: integer
                      tcp_connection:
                        description: TCP Connection time (in milliseconds)
                        type: integer
                      tls_handshake:
                        description: TLS Handshake time (in milliseconds)
                        type: integer
                      total:
                        description: Total time (in milliseconds)
                        type: integer
                      ttfb:
                        description: Time to First Byte (in milliseconds)
                        type: integer
                  http_version:
                    type: integer
                  http_status:
                    type: integer
                  response_headers:
                    type: object
              error:
                description: >-
                  Contains error code and description(Present only if status
                  failed)
                type:
                  - object
                  - 'null'
                properties:
                  code:
                    description: Error code
                    type: string
                  message:
                    description: Error message describing the summary of ttfb error
                    type: string
    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:
    ttfb_result:
      value:
        url: https://speedvitals.com
        region: america
        result:
          - location_id: del
            location_name: Delhi
            status: success
            data:
              timings:
                dns_lookup: 2
                server_processing: 18
                tcp_connection: 10
                tls_handshake: 25
                total: 56
                ttfb: 55
              http_version: 2
              http_status: 200
              response_headers:
                accept-ranges: bytes
                age: 520141
                cache-control: max-age=604800
                vary: Accept-Encoding
                x-cache: HIT
            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

````