Livepeer metrics API

openapi: 3.1.0
info:
  title: Livepeer API Reference accessControl metrics API
  description: 'Welcome to the Livepeer API reference docs. Here you will find all the

    endpoints exposed on the standard Livepeer API, learn how to use them and

    what they return.

    '
  version: 1.0.0
servers:
- url: https://livepeer.studio/api
security:
- apiKey: []
tags:
- name: metrics
  description: Operations related to metrics api
paths:
  /data/views/now:
    get:
      operationId: getRealtimeViewershipNow
      x-speakeasy-name-override: getRealtimeViewership
      summary: Query realtime viewership
      tags:
      - metrics
      description: 'Requires a private (non-CORS) API key to be used.

        '
      parameters:
      - name: playbackId
        in: query
        description: 'The playback ID to filter the query results. This can be a canonical

          playback ID from Livepeer assets or streams, or dStorage identifiers

          for assets

          '
        schema:
          type: string
      - name: creatorId
        in: query
        description: The creator ID to filter the query results
        schema:
          type: string
      - name: breakdownBy[]
        in: query
        description: 'The list of fields to break down the query results. Specify this

          query-string multiple times to break down by multiple fields.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - playbackId
            - device
            - browser
            - country
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '200':
          description: A list of Metric objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/realtime-viewership-metric'
                x-speakeasy-name-override: data
      x-codeSamples:
      - lang: typescript
        label: getRealtimeViewershipNow
        source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n  apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n  const result = await livepeer.metrics.getRealtimeViewership();\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
      - lang: go
        label: getRealtimeViewershipNow
        source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n    s := livepeergo.New(\n        livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    ctx := context.Background()\n    res, err := s.Metrics.GetRealtimeViewership(ctx, nil, nil, nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.Data != nil {\n        // handle response\n    }\n}"
      - lang: python
        label: getRealtimeViewershipNow
        source: "from livepeer import Livepeer\n\ns = Livepeer(\n    api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.metrics.get_realtime_viewership()\n\nif res.data is not None:\n    # handle response\n    pass"
  /data/views/query:
    get:
      operationId: getViewershipMetrics
      x-speakeasy-name-override: getViewership
      summary: Query viewership metrics
      tags:
      - metrics
      description: 'Requires a private (non-CORS) API key to be used.

        '
      parameters:
      - name: playbackId
        in: query
        description: 'The playback ID to filter the query results. This can be a canonical

          playback ID from Livepeer assets or streams, or dStorage identifiers

          for assets

          '
        schema:
          type: string
      - name: from
        in: query
        description: Start timestamp for the query range (inclusive)
        schema:
          oneOf:
          - type: string
            format: date-time
          - type: integer
      - name: to
        in: query
        description: End timestamp for the query range (exclusive)
        schema:
          oneOf:
          - type: string
            format: date-time
          - type: integer
      - name: timeStep
        in: query
        description: The time step to aggregate viewership metrics by
        schema:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
      - name: assetId
        in: query
        description: The asset ID to filter metrics for
        schema:
          type: string
      - name: streamId
        in: query
        description: The stream ID to filter metrics for
        schema:
          type: string
      - name: creatorId
        in: query
        description: The creator ID to filter the query results
        schema:
          type: string
      - name: breakdownBy[]
        in: query
        description: 'The list of fields to break down the query results. Specify this

          query-string multiple times to break down by multiple fields.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - playbackId
            - deviceType
            - device
            - cpu
            - os
            - browser
            - browserEngine
            - continent
            - country
            - subdivision
            - timezone
            - geohash
            - viewerId
            - creatorId
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '200':
          description: A list of Metric objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/viewership-metric'
                x-speakeasy-name-override: data
      x-codeSamples:
      - lang: typescript
        label: getViewershipMetrics
        source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n  apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n  const result = await livepeer.metrics.getViewership({});\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
      - lang: go
        label: getViewershipMetrics
        source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"github.com/livepeer/livepeer-go/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n    s := livepeergo.New(\n        livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    ctx := context.Background()\n    res, err := s.Metrics.GetViewership(ctx, operations.GetViewershipMetricsRequest{})\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.Data != nil {\n        // handle response\n    }\n}"
      - lang: python
        label: getViewershipMetrics
        source: "from livepeer import Livepeer\n\ns = Livepeer(\n    api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.metrics.get_viewership(request={})\n\nif res.data is not None:\n    # handle response\n    pass"
  /data/views/query/creator:
    get:
      operationId: getCreatorViewershipMetrics
      x-speakeasy-name-override: getCreatorViewership
      summary: Query creator viewership metrics
      tags:
      - metrics
      description: 'Requires a proof of ownership to be sent in the request, which for now is just the assetId or streamId parameters (1 of those must be in the query-string).

        '
      parameters:
      - name: from
        in: query
        description: Start timestamp for the query range (inclusive)
        schema:
          oneOf:
          - type: string
            format: date-time
          - type: integer
      - name: to
        in: query
        description: End timestamp for the query range (exclusive)
        schema:
          oneOf:
          - type: string
            format: date-time
          - type: integer
      - name: timeStep
        in: query
        description: The time step to aggregate viewership metrics by
        schema:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
      - name: assetId
        in: query
        description: The asset ID to filter metrics for
        schema:
          type: string
      - name: streamId
        in: query
        description: The stream ID to filter metrics for
        schema:
          type: string
      - name: creatorId
        in: query
        description: The creator ID to filter the query results
        schema:
          type: string
      - name: breakdownBy[]
        in: query
        description: 'The list of fields to break down the query results. Specify this

          query-string multiple times to break down by multiple fields.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - deviceType
            - device
            - cpu
            - os
            - browser
            - browserEngine
            - continent
            - country
            - subdivision
            - timezone
            - viewerId
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '200':
          description: A list of Metric objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/viewership-metric'
                x-speakeasy-name-override: data
      x-codeSamples:
      - lang: typescript
        label: getCreatorViewershipMetrics
        source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n  apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n  const result = await livepeer.metrics.getCreatorViewership({});\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
      - lang: go
        label: getCreatorViewershipMetrics
        source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"github.com/livepeer/livepeer-go/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n    s := livepeergo.New(\n        livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    ctx := context.Background()\n    res, err := s.Metrics.GetCreatorViewership(ctx, operations.GetCreatorViewershipMetricsRequest{})\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.Data != nil {\n        // handle response\n    }\n}"
      - lang: python
        label: getCreatorViewershipMetrics
        source: "from livepeer import Livepeer\n\ns = Livepeer(\n    api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.metrics.get_creator_viewership(request={})\n\nif res.data is not None:\n    # handle response\n    pass"
  /data/views/query/total/{playbackId}:
    get:
      operationId: getPublicViewershipMetrics
      x-speakeasy-name-override: getPublicViewership
      summary: Query public total views metrics
      tags:
      - metrics
      description: 'Allows querying for the public metrics for viewership about a video.

        This can be called from the frontend with a CORS key, or even

        unauthenticated.

        '
      parameters:
      - name: playbackId
        in: path
        required: true
        description: 'The playback ID to filter the query results. This can be a canonical

          playback ID from Livepeer assets or streams, or dStorage identifiers

          for assets

          '
        schema:
          type: string
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '200':
          description: A single Metric object with the viewCount and playtimeMins metrics.
          content:
            application/json:
              schema:
                type: object
                description: 'A simplified metric object about aggregate viewership of an

                  asset. Either playbackId or dStorageUrl will be set.

                  '
                properties:
                  playbackId:
                    $ref: '#/components/schemas/viewership-metric/properties/playbackId'
                  dStorageUrl:
                    $ref: '#/components/schemas/viewership-metric/properties/dStorageUrl'
                  viewCount:
                    $ref: '#/components/schemas/viewership-metric/properties/viewCount'
                  playtimeMins:
                    $ref: '#/components/schemas/viewership-metric/properties/playtimeMins'
                x-speakeasy-name-override: data
      x-codeSamples:
      - lang: typescript
        label: getPublicViewershipMetrics
        source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n  apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n  const result = await livepeer.metrics.getPublicViewership(\"<id>\");\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
      - lang: go
        label: getPublicViewershipMetrics
        source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n    s := livepeergo.New(\n        livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    ctx := context.Background()\n    res, err := s.Metrics.GetPublicViewership(ctx, \"<value>\")\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.Data != nil {\n        // handle response\n    }\n}"
      - lang: python
        label: getPublicViewershipMetrics
        source: "from livepeer import Livepeer\n\ns = Livepeer(\n    api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.metrics.get_public_viewership(playback_id=\"<value>\")\n\nif res.data is not None:\n    # handle response\n    pass"
  /data/usage/query:
    get:
      operationId: getUsageMetrics
      x-speakeasy-name-override: getUsage
      tags:
      - metrics
      summary: Query usage metrics
      parameters:
      - name: from
        in: query
        description: 'Start millis timestamp for the query range (inclusive)

          '
        schema:
          type: integer
      - name: to
        in: query
        description: 'End millis timestamp for the query range (exclusive)

          '
        schema:
          type: integer
      - name: timeStep
        in: query
        description: 'The time step to aggregate viewership metrics by

          '
        schema:
          type: string
          enum:
          - hour
          - day
      - name: creatorId
        in: query
        description: 'The creator ID to filter the query results

          '
        schema:
          type: string
      - name: breakdownBy[]
        in: query
        description: 'The list of fields to break down the query results. Currently the

          only supported breakdown is by `creatorId`.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - creatorId
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '200':
          description: A Usage Metric object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usage-metric'
                x-speakeasy-name-override: data
      x-codeSamples:
      - lang: typescript
        label: getUsageMetrics
        source: "import { Livepeer } from \"livepeer\";\n\nconst livepeer = new Livepeer({\n  apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n  const result = await livepeer.metrics.getUsage({});\n\n  // Handle the result\n  console.log(result);\n}\n\nrun();"
      - lang: go
        label: getUsageMetrics
        source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"github.com/livepeer/livepeer-go/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n    s := livepeergo.New(\n        livepeergo.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    ctx := context.Background()\n    res, err := s.Metrics.GetUsage(ctx, operations.GetUsageMetricsRequest{})\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.UsageMetric != nil {\n        // handle response\n    }\n}"
      - lang: python
        label: getUsageMetrics
        source: "from livepeer import Livepeer\n\ns = Livepeer(\n    api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.metrics.get_usage(request={})\n\nif res.usage_metric is not None:\n    # handle response\n    pass"
components:
  schemas:
    viewership-metric:
      type: object
      description: 'An individual metric about viewership of a stream/asset. Necessarily, at least

        1 of playbackId and dStorageUrl will be present, depending on the query.

        '
      required:
      - viewCount
      - playtimeMins
      properties:
        playbackId:
          type: string
          description: The playback ID associated with the metric.
          example: 1bde4o2i6xycudoy
        creatorId:
          type: string
          description: The ID of the creator associated with the metric.
          example: john@doe.com
        viewerId:
          type: string
          description: The ID of the viewer associated with the metric.
          example: 1bde4o2i6xycudoy
        dStorageUrl:
          type: string
          description: The URL of the distributed storage used for the asset
          example: ipfs://QmZ4
        timestamp:
          type: number
          example: 1587667174725
          description: 'Timestamp (in milliseconds) when the metric was recorded. If the

            query contains a time step, this timestamp will point to the

            beginning of the time step period.

            '
        device:
          type: string
          description: The device used by the viewer.
          example: iPhone
        deviceType:
          type: string
          description: The type of the device used by the viewer.
          example: mobile
        cpu:
          type: string
          description: The CPU used by the viewer's device.
          example: ARM
        os:
          type: string
          description: The operating system used by the viewer.
          example: iOS
        browser:
          type: string
          description: The browser used by the viewer.
          example: Safari
        browserEngine:
          type: string
          description: The browser engine used by the viewer's browser.
          example: WebKit
        continent:
          type: string
          description: The continent where the viewer is located.
          example: North America
        country:
          type: string
          description: The country where the viewer is located.
          example: United States
        subdivision:
          type: string
          description: 'The subdivision (e.g., state or province) where the viewer is

            located.

            '
          example: California
        timezone:
          type: string
          description: The timezone where the viewer is located.
          example: America/Los_Angeles
        geohash:
          type: string
          description: Geographic encoding of the viewers location. Accurate to 3 digits.
          example: 123
        viewCount:
          type: integer
          description: The number of views for the stream/asset.
          example: 100
        playtimeMins:
          type: number
          description: The total playtime in minutes for the stream/asset.
          example: 10
        ttffMs:
          type: number
          description: The time-to-first-frame (TTFF) in milliseconds.
          example: 100
        rebufferRatio:
          type: number
          description: The rebuffering ratio for the asset.
          example: 0.1
        errorRate:
          type: number
          description: The error rate for the stream/asset.
          example: 0.1
        exitsBeforeStart:
          type: number
          description: 'The percentage of sessions that existed before the asset started

            playing.

            '
          example: 0.5
    error:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: string
            example:
            - id not provided
            - Account not found
    realtime-viewership-metric:
      type: object
      description: 'An individual metric about realtime viewership of a stream/asset.

        '
      required:
      - viewCount
      - errorRate
      properties:
        playbackId:
          type: string
          description: The playback ID associated with the metric.
          example: 1bde4o2i6xycudoy
        device:
          type: string
          description: The device used by the viewer.
          example: iPhone
        browser:
          type: string
          description: The browser used by the viewer.
          example: Safari
        country:
          type: string
          description: The country where the viewer is located.
          example: United States
        viewCount:
          type: integer
          description: The number of views for the stream/asset.
          example: 100
        errorRate:
          type: number
          description: The error rate for the stream/asset.
          example: 0.1
    usage-metric:
      type: object
      description: 'An individual metric about usage of a user.

        '
      properties:
        UserID:
          type: string
          description: The user ID associated with the metric
          example: 1bde4o2i6xycudoy
        CreatorID:
          type: string
          description: The creator ID associated with the metric
          example: john@doe.com
        DeliveryUsageMins:
          type: number
          description: Total minutes of delivery usage.
          example: 100
        TotalUsageMins:
          type: number
          description: Total transcoded minutes.
          example: 100
        StorageUsageMins:
          type: number
          description: Total minutes of storage usage.
          example: 100
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
    HTTPBearer:
      type: http
      scheme: bearer