> ## Documentation Index > Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt > Use this file to discover all available pages before exploring further. # Query viewership metrics > Requires a private (non-CORS) API key to be used. ## OpenAPI ````yaml GET /data/views/query openapi: 3.1.0 info: title: Livepeer API Reference 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: stream description: Operations related to livestream api - name: asset description: Operations related to asset/vod api - name: webhook description: Operations related to webhook api - name: multistream description: Operations related to multistream api - name: session description: Operations related to session api - name: room description: Operations related to rooms api - name: transcode description: Operations related to transcode api - name: metrics description: Operations related to metrics api - name: playback description: Operations related to playback api - name: accessControl description: Operations related to access control/signing keys api - name: task description: Operations related to tasks api - name: generate description: Operations related to AI generate api paths: /data/views/query: get: tags: - metrics summary: Query viewership metrics description: | Requires a private (non-CORS) API key to be used. operationId: getViewershipMetrics 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: '200': description: A list of Metric objects content: application/json: schema: type: array items: $ref: '#/components/schemas/viewership-metric' x-speakeasy-name-override: data default: description: Error content: application/json: schema: $ref: '#/components/schemas/error' x-codeSamples: - lang: typescript label: getViewershipMetrics source: |- import { Livepeer } from "livepeer"; const livepeer = new Livepeer({ apiKey: "", }); async function run() { const result = await livepeer.metrics.getViewership({}); // Handle the result console.log(result); } run(); - 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(\"\"),\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 s = Livepeer( api_key="", ) res = s.metrics.get_viewership(request={}) if res.data is not None: # handle response 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 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: JWT ````