chunkify-analytics-sdk 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. chunkify_analytics/__init__.py +102 -0
  2. chunkify_analytics/_base_client.py +2153 -0
  3. chunkify_analytics/_client.py +1262 -0
  4. chunkify_analytics/_compat.py +226 -0
  5. chunkify_analytics/_constants.py +14 -0
  6. chunkify_analytics/_exceptions.py +108 -0
  7. chunkify_analytics/_files.py +173 -0
  8. chunkify_analytics/_models.py +964 -0
  9. chunkify_analytics/_qs.py +149 -0
  10. chunkify_analytics/_resource.py +43 -0
  11. chunkify_analytics/_response.py +835 -0
  12. chunkify_analytics/_streaming.py +338 -0
  13. chunkify_analytics/_types.py +274 -0
  14. chunkify_analytics/_utils/__init__.py +64 -0
  15. chunkify_analytics/_utils/_compat.py +45 -0
  16. chunkify_analytics/_utils/_datetime_parse.py +136 -0
  17. chunkify_analytics/_utils/_json.py +35 -0
  18. chunkify_analytics/_utils/_logs.py +25 -0
  19. chunkify_analytics/_utils/_path.py +127 -0
  20. chunkify_analytics/_utils/_proxy.py +65 -0
  21. chunkify_analytics/_utils/_reflection.py +42 -0
  22. chunkify_analytics/_utils/_resources_proxy.py +24 -0
  23. chunkify_analytics/_utils/_streams.py +12 -0
  24. chunkify_analytics/_utils/_sync.py +58 -0
  25. chunkify_analytics/_utils/_transform.py +457 -0
  26. chunkify_analytics/_utils/_typing.py +156 -0
  27. chunkify_analytics/_utils/_utils.py +433 -0
  28. chunkify_analytics/_version.py +4 -0
  29. chunkify_analytics/lib/.keep +4 -0
  30. chunkify_analytics/pagination.py +221 -0
  31. chunkify_analytics/py.typed +0 -0
  32. chunkify_analytics/resources/__init__.py +243 -0
  33. chunkify_analytics/resources/admin/__init__.py +33 -0
  34. chunkify_analytics/resources/admin/admin.py +253 -0
  35. chunkify_analytics/resources/admin/keys.py +283 -0
  36. chunkify_analytics/resources/dimensions.py +436 -0
  37. chunkify_analytics/resources/engagement.py +479 -0
  38. chunkify_analytics/resources/errors.py +400 -0
  39. chunkify_analytics/resources/events.py +562 -0
  40. chunkify_analytics/resources/exports.py +584 -0
  41. chunkify_analytics/resources/health.py +159 -0
  42. chunkify_analytics/resources/playback_rates.py +391 -0
  43. chunkify_analytics/resources/project/__init__.py +33 -0
  44. chunkify_analytics/resources/project/keys.py +379 -0
  45. chunkify_analytics/resources/project/project.py +322 -0
  46. chunkify_analytics/resources/quality.py +471 -0
  47. chunkify_analytics/resources/renditions.py +391 -0
  48. chunkify_analytics/resources/retention.py +377 -0
  49. chunkify_analytics/resources/subtitles.py +389 -0
  50. chunkify_analytics/resources/summary.py +469 -0
  51. chunkify_analytics/resources/timeseries.py +399 -0
  52. chunkify_analytics/resources/videos.py +424 -0
  53. chunkify_analytics/resources/views.py +579 -0
  54. chunkify_analytics/types/__init__.py +145 -0
  55. chunkify_analytics/types/admin/__init__.py +3 -0
  56. chunkify_analytics/types/admin_create_project_params.py +25 -0
  57. chunkify_analytics/types/analytics_event.py +32 -0
  58. chunkify_analytics/types/analytics_event_param.py +30 -0
  59. chunkify_analytics/types/created_project.py +37 -0
  60. chunkify_analytics/types/created_project_key.py +34 -0
  61. chunkify_analytics/types/deleted_project.py +18 -0
  62. chunkify_analytics/types/dimension_list_values_params.py +124 -0
  63. chunkify_analytics/types/dimension_values.py +42 -0
  64. chunkify_analytics/types/engagement.py +60 -0
  65. chunkify_analytics/types/engagement_breakdown_page.py +44 -0
  66. chunkify_analytics/types/engagement_response.py +11 -0
  67. chunkify_analytics/types/engagement_retrieve_params.py +158 -0
  68. chunkify_analytics/types/engagement_timeseries.py +28 -0
  69. chunkify_analytics/types/engagement_timeseries_bucket.py +63 -0
  70. chunkify_analytics/types/error_group.py +17 -0
  71. chunkify_analytics/types/error_list_params.py +124 -0
  72. chunkify_analytics/types/error_page.py +14 -0
  73. chunkify_analytics/types/event_ingest_params.py +19 -0
  74. chunkify_analytics/types/event_ingest_response.py +11 -0
  75. chunkify_analytics/types/event_list_params.py +146 -0
  76. chunkify_analytics/types/event_page.py +18 -0
  77. chunkify_analytics/types/export.py +18 -0
  78. chunkify_analytics/types/export_columns.py +12 -0
  79. chunkify_analytics/types/export_create_params.py +40 -0
  80. chunkify_analytics/types/export_download_response.py +7 -0
  81. chunkify_analytics/types/export_list_columns_params.py +69 -0
  82. chunkify_analytics/types/export_query_param.py +141 -0
  83. chunkify_analytics/types/health.py +11 -0
  84. chunkify_analytics/types/metrics.py +13 -0
  85. chunkify_analytics/types/metrics_breakdown_page.py +40 -0
  86. chunkify_analytics/types/metrics_response.py +11 -0
  87. chunkify_analytics/types/native_created.py +13 -0
  88. chunkify_analytics/types/native_duplicate.py +13 -0
  89. chunkify_analytics/types/playback_error.py +180 -0
  90. chunkify_analytics/types/playback_error_param.py +182 -0
  91. chunkify_analytics/types/playback_rate_changed.py +150 -0
  92. chunkify_analytics/types/playback_rate_changed_param.py +152 -0
  93. chunkify_analytics/types/playback_rate_metric.py +21 -0
  94. chunkify_analytics/types/playback_rate_report.py +31 -0
  95. chunkify_analytics/types/playback_rate_retrieve_params.py +117 -0
  96. chunkify_analytics/types/playback_state_changed.py +150 -0
  97. chunkify_analytics/types/playback_state_changed_param.py +156 -0
  98. chunkify_analytics/types/project/__init__.py +6 -0
  99. chunkify_analytics/types/project/key_create_params.py +21 -0
  100. chunkify_analytics/types/project/project.py +35 -0
  101. chunkify_analytics/types/project_key.py +21 -0
  102. chunkify_analytics/types/project_keys.py +14 -0
  103. chunkify_analytics/types/project_update_params.py +25 -0
  104. chunkify_analytics/types/quality.py +117 -0
  105. chunkify_analytics/types/quality_breakdown_page.py +44 -0
  106. chunkify_analytics/types/quality_response.py +11 -0
  107. chunkify_analytics/types/quality_retrieve_params.py +158 -0
  108. chunkify_analytics/types/quality_timeseries.py +28 -0
  109. chunkify_analytics/types/quality_timeseries_bucket.py +120 -0
  110. chunkify_analytics/types/rendition_changed.py +156 -0
  111. chunkify_analytics/types/rendition_changed_param.py +158 -0
  112. chunkify_analytics/types/rendition_metric.py +40 -0
  113. chunkify_analytics/types/rendition_report.py +43 -0
  114. chunkify_analytics/types/rendition_retrieve_params.py +117 -0
  115. chunkify_analytics/types/retention_bucket.py +22 -0
  116. chunkify_analytics/types/retention_report.py +33 -0
  117. chunkify_analytics/types/retention_retrieve_params.py +110 -0
  118. chunkify_analytics/types/rotated_project_key.py +29 -0
  119. chunkify_analytics/types/seek_completed.py +166 -0
  120. chunkify_analytics/types/seek_completed_param.py +168 -0
  121. chunkify_analytics/types/shared/__init__.py +24 -0
  122. chunkify_analytics/types/shared/browser_context.py +62 -0
  123. chunkify_analytics/types/shared/custom_dimensions.py +8 -0
  124. chunkify_analytics/types/shared/event_context.py +161 -0
  125. chunkify_analytics/types/shared/event_envelope.py +152 -0
  126. chunkify_analytics/types/shared/metric_count_ratio.py +18 -0
  127. chunkify_analytics/types/shared/otlp_any_value.py +56 -0
  128. chunkify_analytics/types/shared/otlp_attribute.py +24 -0
  129. chunkify_analytics/types/shared/otlp_attribute_value.py +136 -0
  130. chunkify_analytics/types/shared/otlp_context_attribute.py +22 -0
  131. chunkify_analytics/types/shared/otlp_log_record.py +48 -0
  132. chunkify_analytics/types/shared/otlp_resource.py +20 -0
  133. chunkify_analytics/types/shared/otlp_scope.py +24 -0
  134. chunkify_analytics/types/shared/playback_rate_playing_time.py +12 -0
  135. chunkify_analytics/types/shared/playback_score.py +28 -0
  136. chunkify_analytics/types/shared/played_range.py +13 -0
  137. chunkify_analytics/types/shared/progress_reached.py +39 -0
  138. chunkify_analytics/types/shared/rendition_playing_time.py +21 -0
  139. chunkify_analytics/types/shared/startup_outcomes.py +39 -0
  140. chunkify_analytics/types/shared/stored_otlp_context.py +50 -0
  141. chunkify_analytics/types/shared/subtitle_playing_time.py +14 -0
  142. chunkify_analytics/types/shared/view_metrics.py +100 -0
  143. chunkify_analytics/types/shared/watch_time_distribution.py +41 -0
  144. chunkify_analytics/types/shared_params/__init__.py +8 -0
  145. chunkify_analytics/types/shared_params/browser_context.py +62 -0
  146. chunkify_analytics/types/shared_params/custom_dimensions.py +10 -0
  147. chunkify_analytics/types/shared_params/playback_rate_playing_time.py +14 -0
  148. chunkify_analytics/types/shared_params/played_range.py +15 -0
  149. chunkify_analytics/types/shared_params/rendition_playing_time.py +22 -0
  150. chunkify_analytics/types/shared_params/subtitle_playing_time.py +15 -0
  151. chunkify_analytics/types/stored_event.py +44 -0
  152. chunkify_analytics/types/subtitle_changed.py +150 -0
  153. chunkify_analytics/types/subtitle_changed_param.py +152 -0
  154. chunkify_analytics/types/subtitle_metric.py +26 -0
  155. chunkify_analytics/types/subtitle_report.py +31 -0
  156. chunkify_analytics/types/subtitle_retrieve_params.py +117 -0
  157. chunkify_analytics/types/summary_retrieve_params.py +158 -0
  158. chunkify_analytics/types/time_bucket.py +22 -0
  159. chunkify_analytics/types/timeseries.py +28 -0
  160. chunkify_analytics/types/timeseries_response.py +12 -0
  161. chunkify_analytics/types/timesery_retrieve_params.py +115 -0
  162. chunkify_analytics/types/video_list_params.py +140 -0
  163. chunkify_analytics/types/video_metrics.py +23 -0
  164. chunkify_analytics/types/video_page.py +14 -0
  165. chunkify_analytics/types/view.py +43 -0
  166. chunkify_analytics/types/view_detail.py +21 -0
  167. chunkify_analytics/types/view_ended.py +180 -0
  168. chunkify_analytics/types/view_ended_param.py +182 -0
  169. chunkify_analytics/types/view_list_params.py +152 -0
  170. chunkify_analytics/types/view_page.py +14 -0
  171. chunkify_analytics/types/view_retrieve_params.py +23 -0
  172. chunkify_analytics/types/view_snapshot.py +180 -0
  173. chunkify_analytics/types/view_snapshot_param.py +182 -0
  174. chunkify_analytics/types/view_started.py +192 -0
  175. chunkify_analytics/types/view_started_param.py +194 -0
  176. chunkify_analytics_sdk-0.9.0.dist-info/METADATA +487 -0
  177. chunkify_analytics_sdk-0.9.0.dist-info/RECORD +179 -0
  178. chunkify_analytics_sdk-0.9.0.dist-info/WHEEL +4 -0
  179. chunkify_analytics_sdk-0.9.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,479 @@
1
+ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Union, cast
6
+ from datetime import datetime
7
+ from typing_extensions import Literal
8
+
9
+ import httpx
10
+
11
+ from ..types import engagement_retrieve_params
12
+ from .._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
13
+ from .._utils import maybe_transform, async_maybe_transform
14
+ from .._compat import cached_property
15
+ from .._resource import SyncAPIResource, AsyncAPIResource
16
+ from .._response import (
17
+ to_raw_response_wrapper,
18
+ to_streamed_response_wrapper,
19
+ async_to_raw_response_wrapper,
20
+ async_to_streamed_response_wrapper,
21
+ )
22
+ from .._base_client import make_request_options
23
+ from ..types.engagement_response import EngagementResponse
24
+
25
+ __all__ = ["EngagementResource", "AsyncEngagementResource"]
26
+
27
+
28
+ class EngagementResource(SyncAPIResource):
29
+ """Private retained-event and view-cohort queries."""
30
+
31
+ @cached_property
32
+ def with_raw_response(self) -> EngagementResourceWithRawResponse:
33
+ """
34
+ This property can be used as a prefix for any HTTP method call to return
35
+ the raw response object instead of the parsed content.
36
+
37
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#accessing-raw-response-data-eg-headers
38
+ """
39
+ return EngagementResourceWithRawResponse(self)
40
+
41
+ @cached_property
42
+ def with_streaming_response(self) -> EngagementResourceWithStreamingResponse:
43
+ """
44
+ An alternative to `.with_raw_response` that doesn't eagerly read the response body.
45
+
46
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#with_streaming_response
47
+ """
48
+ return EngagementResourceWithStreamingResponse(self)
49
+
50
+ def retrieve(
51
+ self,
52
+ *,
53
+ browser_name: str | Omit = omit,
54
+ city: str | Omit = omit,
55
+ continent: Literal["AF", "AN", "AS", "EU", "NA", "OC", "SA"] | Omit = omit,
56
+ country: str | Omit = omit,
57
+ cursor: str | Omit = omit,
58
+ device_type: Literal["desktop", "mobile", "tablet", "unknown"] | Omit = omit,
59
+ from_: Union[str, datetime] | Omit = omit,
60
+ group_by: Union[
61
+ Literal[
62
+ "browser_name",
63
+ "os_name",
64
+ "device_type",
65
+ "continent",
66
+ "country",
67
+ "city",
68
+ "page_origin",
69
+ "page_path",
70
+ "subtitle_language",
71
+ "playback_rate",
72
+ "video_title",
73
+ "user_id",
74
+ ],
75
+ str,
76
+ ]
77
+ | Omit = omit,
78
+ limit: int | Omit = omit,
79
+ os_name: str | Omit = omit,
80
+ page_origin: str | Omit = omit,
81
+ page_path: str | Omit = omit,
82
+ playback_rate: str | Omit = omit,
83
+ subtitle_language: str | Omit = omit,
84
+ to: Union[str, datetime] | Omit = omit,
85
+ user_id: str | Omit = omit,
86
+ video_id: str | Omit = omit,
87
+ video_title: str | Omit = omit,
88
+ view_id: str | Omit = omit,
89
+ viewer_id: str | Omit = omit,
90
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
91
+ # The extra values given here take precedence over values defined on the client or passed to this method.
92
+ extra_headers: Headers | None = None,
93
+ extra_query: Query | None = None,
94
+ extra_body: Body | None = None,
95
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
96
+ ) -> EngagementResponse:
97
+ """Get average watch time per attempt and the observed reached-end rate.
98
+
99
+ Reaching
100
+ the end does not prove the whole video was watched. Optionally group the full
101
+ filtered view-start cohort with group_by=browser_name, os_name, device_type,
102
+ continent, country or city. Without group_by the totals response is unchanged.
103
+ With group_by, return paginated groups sorted by views descending. Equal view
104
+ counts sort by value ascending, null first. Context comes from the first
105
+ retained start; missing, null and nonstring values form a null group. Keep
106
+ group_by and filters unchanged with each cursor. Unique viewers must not be
107
+ summed across groups. Includes furthest-progress milestones and measured
108
+ watch-time distribution. Progress can include seeking and is not retention.
109
+
110
+ Args:
111
+ browser_name: Exact browser name, such as Chrome. Missing values do not match.
112
+
113
+ city: Exact, case-sensitive city name from the local lookup, with 1 to 256 Unicode
114
+ characters. Use country alongside city to distinguish places with the same name.
115
+ Missing locations do not match.
116
+
117
+ continent: Exact continent code from the local lookup. Missing locations do not match.
118
+
119
+ country: Exact uppercase ISO 3166-1 alpha-2 country code, such as GB. Missing locations
120
+ do not match.
121
+
122
+ cursor: Use next_cursor from the previous page. Keep the same filters, sort_by and
123
+ order. Video cursors from earlier versions are invalid; start a new pagination
124
+ sequence after upgrading.
125
+
126
+ device_type: Exact device class. unknown matches an explicit unknown value.
127
+
128
+ from_: Inclusive RFC3339 occurrence-time lower bound, with timezone. Summary/video
129
+ queries apply it to the selected view_started event. Must be before to.
130
+
131
+ group_by: Optional on summary, quality and engagement. Group views by this field on their
132
+ first retained start. Missing, null and nonstring context forms a null group;
133
+ the literal device type unknown stays separate. Groups sort by views descending,
134
+ then value ascending with null first for ties. Pagination is available only with
135
+ group_by. Location uses the first retained start too. City groups use the stored
136
+ name; filter by country to avoid combining names shared by different countries.
137
+ Page groups use the first retained start even if playback continues after
138
+ navigation. Filter by page_origin when grouping page_path to distinguish
139
+ identical paths on different sites. video_title groups by the title on each
140
+ view's first retained start, so a renamed video counts each view under the title
141
+ it started with. user_id groups by the user ID on each view's first retained
142
+ start. Use custom.<key>, such as custom.plan, to group by a custom dimension;
143
+ views without the key form the null group.
144
+
145
+ limit: Maximum rows on this page. Events and videos always support pagination; summary,
146
+ quality and engagement support it only with group_by.
147
+
148
+ os_name: Exact operating-system name, such as macOS. Missing values do not match.
149
+
150
+ page_origin: Exact, case-sensitive page origin captured by the player, such as
151
+ https://example.com. Metrics use the first retained view start; raw events use
152
+ each event context. Missing values do not match.
153
+
154
+ page_path: Exact, case-sensitive page path captured by the player, such as /watch/video.
155
+ Filter by page_origin as well to distinguish identical paths on different sites.
156
+ Metrics use the first retained view start; raw events use each event context.
157
+ Missing values do not match.
158
+
159
+ playback_rate: Playback rate from 0.01 to 16 with at most two decimals, such as 1, 1.5 or 2;
160
+ 2.0 and 2 are the same rate. Metrics use the rate on the first retained view
161
+ start; raw events use each event's value.
162
+
163
+ subtitle_language: Exact, case-sensitive, non-blank subtitle language tag, such as fr or en-US; und
164
+ for a subtitles track without a language. Metrics use the language showing on
165
+ the first retained view start; raw events use each event's value. Views without
166
+ subtitles at start do not match.
167
+
168
+ to: Exclusive RFC3339 occurrence-time upper bound, with timezone. Summary/video
169
+ queries apply it to the selected view_started event.
170
+
171
+ user_id: Exact integrator-supplied user ID. Selects views by their start event; event
172
+ lists match each event's own value. Missing/null user IDs do not match. Reports
173
+ with this filter read one stored row per view.
174
+
175
+ video_id: Exact video ID; must not be blank. Combined with all other filters using AND.
176
+
177
+ video_title: Exact, case-sensitive video title. Selects views by the title on their first
178
+ retained start; event lists match each event's own value. Views without a title
179
+ do not match. Reports with this filter read one stored row per view.
180
+
181
+ view_id: Filter one playback attempt by view ID. Metrics use its first retained start.
182
+
183
+ viewer_id: Exact viewer ID. The Chunkify player SDK generates one per browser; missing/null
184
+ viewer IDs do not match.
185
+
186
+ extra_headers: Send extra headers
187
+
188
+ extra_query: Add additional query parameters to the request
189
+
190
+ extra_body: Add additional JSON properties to the request
191
+
192
+ timeout: Override the client-level default timeout for this request, in seconds
193
+ """
194
+ return cast(
195
+ EngagementResponse,
196
+ self._get(
197
+ "/v1/engagement",
198
+ options=make_request_options(
199
+ extra_headers=extra_headers,
200
+ extra_query=extra_query,
201
+ extra_body=extra_body,
202
+ timeout=timeout,
203
+ query=maybe_transform(
204
+ {
205
+ "browser_name": browser_name,
206
+ "city": city,
207
+ "continent": continent,
208
+ "country": country,
209
+ "cursor": cursor,
210
+ "device_type": device_type,
211
+ "from_": from_,
212
+ "group_by": group_by,
213
+ "limit": limit,
214
+ "os_name": os_name,
215
+ "page_origin": page_origin,
216
+ "page_path": page_path,
217
+ "playback_rate": playback_rate,
218
+ "subtitle_language": subtitle_language,
219
+ "to": to,
220
+ "user_id": user_id,
221
+ "video_id": video_id,
222
+ "video_title": video_title,
223
+ "view_id": view_id,
224
+ "viewer_id": viewer_id,
225
+ },
226
+ engagement_retrieve_params.EngagementRetrieveParams,
227
+ ),
228
+ security={"secret_key": True},
229
+ ),
230
+ cast_to=cast(
231
+ Any, EngagementResponse
232
+ ), # Union types cannot be passed in as arguments in the type system
233
+ ),
234
+ )
235
+
236
+
237
+ class AsyncEngagementResource(AsyncAPIResource):
238
+ """Private retained-event and view-cohort queries."""
239
+
240
+ @cached_property
241
+ def with_raw_response(self) -> AsyncEngagementResourceWithRawResponse:
242
+ """
243
+ This property can be used as a prefix for any HTTP method call to return
244
+ the raw response object instead of the parsed content.
245
+
246
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#accessing-raw-response-data-eg-headers
247
+ """
248
+ return AsyncEngagementResourceWithRawResponse(self)
249
+
250
+ @cached_property
251
+ def with_streaming_response(self) -> AsyncEngagementResourceWithStreamingResponse:
252
+ """
253
+ An alternative to `.with_raw_response` that doesn't eagerly read the response body.
254
+
255
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#with_streaming_response
256
+ """
257
+ return AsyncEngagementResourceWithStreamingResponse(self)
258
+
259
+ async def retrieve(
260
+ self,
261
+ *,
262
+ browser_name: str | Omit = omit,
263
+ city: str | Omit = omit,
264
+ continent: Literal["AF", "AN", "AS", "EU", "NA", "OC", "SA"] | Omit = omit,
265
+ country: str | Omit = omit,
266
+ cursor: str | Omit = omit,
267
+ device_type: Literal["desktop", "mobile", "tablet", "unknown"] | Omit = omit,
268
+ from_: Union[str, datetime] | Omit = omit,
269
+ group_by: Union[
270
+ Literal[
271
+ "browser_name",
272
+ "os_name",
273
+ "device_type",
274
+ "continent",
275
+ "country",
276
+ "city",
277
+ "page_origin",
278
+ "page_path",
279
+ "subtitle_language",
280
+ "playback_rate",
281
+ "video_title",
282
+ "user_id",
283
+ ],
284
+ str,
285
+ ]
286
+ | Omit = omit,
287
+ limit: int | Omit = omit,
288
+ os_name: str | Omit = omit,
289
+ page_origin: str | Omit = omit,
290
+ page_path: str | Omit = omit,
291
+ playback_rate: str | Omit = omit,
292
+ subtitle_language: str | Omit = omit,
293
+ to: Union[str, datetime] | Omit = omit,
294
+ user_id: str | Omit = omit,
295
+ video_id: str | Omit = omit,
296
+ video_title: str | Omit = omit,
297
+ view_id: str | Omit = omit,
298
+ viewer_id: str | Omit = omit,
299
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
300
+ # The extra values given here take precedence over values defined on the client or passed to this method.
301
+ extra_headers: Headers | None = None,
302
+ extra_query: Query | None = None,
303
+ extra_body: Body | None = None,
304
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
305
+ ) -> EngagementResponse:
306
+ """Get average watch time per attempt and the observed reached-end rate.
307
+
308
+ Reaching
309
+ the end does not prove the whole video was watched. Optionally group the full
310
+ filtered view-start cohort with group_by=browser_name, os_name, device_type,
311
+ continent, country or city. Without group_by the totals response is unchanged.
312
+ With group_by, return paginated groups sorted by views descending. Equal view
313
+ counts sort by value ascending, null first. Context comes from the first
314
+ retained start; missing, null and nonstring values form a null group. Keep
315
+ group_by and filters unchanged with each cursor. Unique viewers must not be
316
+ summed across groups. Includes furthest-progress milestones and measured
317
+ watch-time distribution. Progress can include seeking and is not retention.
318
+
319
+ Args:
320
+ browser_name: Exact browser name, such as Chrome. Missing values do not match.
321
+
322
+ city: Exact, case-sensitive city name from the local lookup, with 1 to 256 Unicode
323
+ characters. Use country alongside city to distinguish places with the same name.
324
+ Missing locations do not match.
325
+
326
+ continent: Exact continent code from the local lookup. Missing locations do not match.
327
+
328
+ country: Exact uppercase ISO 3166-1 alpha-2 country code, such as GB. Missing locations
329
+ do not match.
330
+
331
+ cursor: Use next_cursor from the previous page. Keep the same filters, sort_by and
332
+ order. Video cursors from earlier versions are invalid; start a new pagination
333
+ sequence after upgrading.
334
+
335
+ device_type: Exact device class. unknown matches an explicit unknown value.
336
+
337
+ from_: Inclusive RFC3339 occurrence-time lower bound, with timezone. Summary/video
338
+ queries apply it to the selected view_started event. Must be before to.
339
+
340
+ group_by: Optional on summary, quality and engagement. Group views by this field on their
341
+ first retained start. Missing, null and nonstring context forms a null group;
342
+ the literal device type unknown stays separate. Groups sort by views descending,
343
+ then value ascending with null first for ties. Pagination is available only with
344
+ group_by. Location uses the first retained start too. City groups use the stored
345
+ name; filter by country to avoid combining names shared by different countries.
346
+ Page groups use the first retained start even if playback continues after
347
+ navigation. Filter by page_origin when grouping page_path to distinguish
348
+ identical paths on different sites. video_title groups by the title on each
349
+ view's first retained start, so a renamed video counts each view under the title
350
+ it started with. user_id groups by the user ID on each view's first retained
351
+ start. Use custom.<key>, such as custom.plan, to group by a custom dimension;
352
+ views without the key form the null group.
353
+
354
+ limit: Maximum rows on this page. Events and videos always support pagination; summary,
355
+ quality and engagement support it only with group_by.
356
+
357
+ os_name: Exact operating-system name, such as macOS. Missing values do not match.
358
+
359
+ page_origin: Exact, case-sensitive page origin captured by the player, such as
360
+ https://example.com. Metrics use the first retained view start; raw events use
361
+ each event context. Missing values do not match.
362
+
363
+ page_path: Exact, case-sensitive page path captured by the player, such as /watch/video.
364
+ Filter by page_origin as well to distinguish identical paths on different sites.
365
+ Metrics use the first retained view start; raw events use each event context.
366
+ Missing values do not match.
367
+
368
+ playback_rate: Playback rate from 0.01 to 16 with at most two decimals, such as 1, 1.5 or 2;
369
+ 2.0 and 2 are the same rate. Metrics use the rate on the first retained view
370
+ start; raw events use each event's value.
371
+
372
+ subtitle_language: Exact, case-sensitive, non-blank subtitle language tag, such as fr or en-US; und
373
+ for a subtitles track without a language. Metrics use the language showing on
374
+ the first retained view start; raw events use each event's value. Views without
375
+ subtitles at start do not match.
376
+
377
+ to: Exclusive RFC3339 occurrence-time upper bound, with timezone. Summary/video
378
+ queries apply it to the selected view_started event.
379
+
380
+ user_id: Exact integrator-supplied user ID. Selects views by their start event; event
381
+ lists match each event's own value. Missing/null user IDs do not match. Reports
382
+ with this filter read one stored row per view.
383
+
384
+ video_id: Exact video ID; must not be blank. Combined with all other filters using AND.
385
+
386
+ video_title: Exact, case-sensitive video title. Selects views by the title on their first
387
+ retained start; event lists match each event's own value. Views without a title
388
+ do not match. Reports with this filter read one stored row per view.
389
+
390
+ view_id: Filter one playback attempt by view ID. Metrics use its first retained start.
391
+
392
+ viewer_id: Exact viewer ID. The Chunkify player SDK generates one per browser; missing/null
393
+ viewer IDs do not match.
394
+
395
+ extra_headers: Send extra headers
396
+
397
+ extra_query: Add additional query parameters to the request
398
+
399
+ extra_body: Add additional JSON properties to the request
400
+
401
+ timeout: Override the client-level default timeout for this request, in seconds
402
+ """
403
+ return cast(
404
+ EngagementResponse,
405
+ await self._get(
406
+ "/v1/engagement",
407
+ options=make_request_options(
408
+ extra_headers=extra_headers,
409
+ extra_query=extra_query,
410
+ extra_body=extra_body,
411
+ timeout=timeout,
412
+ query=await async_maybe_transform(
413
+ {
414
+ "browser_name": browser_name,
415
+ "city": city,
416
+ "continent": continent,
417
+ "country": country,
418
+ "cursor": cursor,
419
+ "device_type": device_type,
420
+ "from_": from_,
421
+ "group_by": group_by,
422
+ "limit": limit,
423
+ "os_name": os_name,
424
+ "page_origin": page_origin,
425
+ "page_path": page_path,
426
+ "playback_rate": playback_rate,
427
+ "subtitle_language": subtitle_language,
428
+ "to": to,
429
+ "user_id": user_id,
430
+ "video_id": video_id,
431
+ "video_title": video_title,
432
+ "view_id": view_id,
433
+ "viewer_id": viewer_id,
434
+ },
435
+ engagement_retrieve_params.EngagementRetrieveParams,
436
+ ),
437
+ security={"secret_key": True},
438
+ ),
439
+ cast_to=cast(
440
+ Any, EngagementResponse
441
+ ), # Union types cannot be passed in as arguments in the type system
442
+ ),
443
+ )
444
+
445
+
446
+ class EngagementResourceWithRawResponse:
447
+ def __init__(self, engagement: EngagementResource) -> None:
448
+ self._engagement = engagement
449
+
450
+ self.retrieve = to_raw_response_wrapper(
451
+ engagement.retrieve,
452
+ )
453
+
454
+
455
+ class AsyncEngagementResourceWithRawResponse:
456
+ def __init__(self, engagement: AsyncEngagementResource) -> None:
457
+ self._engagement = engagement
458
+
459
+ self.retrieve = async_to_raw_response_wrapper(
460
+ engagement.retrieve,
461
+ )
462
+
463
+
464
+ class EngagementResourceWithStreamingResponse:
465
+ def __init__(self, engagement: EngagementResource) -> None:
466
+ self._engagement = engagement
467
+
468
+ self.retrieve = to_streamed_response_wrapper(
469
+ engagement.retrieve,
470
+ )
471
+
472
+
473
+ class AsyncEngagementResourceWithStreamingResponse:
474
+ def __init__(self, engagement: AsyncEngagementResource) -> None:
475
+ self._engagement = engagement
476
+
477
+ self.retrieve = async_to_streamed_response_wrapper(
478
+ engagement.retrieve,
479
+ )