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,584 @@
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 Union
6
+ from typing_extensions import Literal
7
+
8
+ import httpx
9
+
10
+ from ..types import export_create_params, export_list_columns_params
11
+ from .._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
12
+ from .._utils import path_template, maybe_transform, async_maybe_transform
13
+ from .._compat import cached_property
14
+ from .._resource import SyncAPIResource, AsyncAPIResource
15
+ from .._response import (
16
+ to_raw_response_wrapper,
17
+ to_streamed_response_wrapper,
18
+ async_to_raw_response_wrapper,
19
+ async_to_streamed_response_wrapper,
20
+ )
21
+ from .._base_client import make_request_options
22
+ from ..types.export import Export
23
+ from ..types.export_columns import ExportColumns
24
+ from ..types.export_query_param import ExportQueryParam
25
+
26
+ __all__ = ["ExportsResource", "AsyncExportsResource"]
27
+
28
+
29
+ class ExportsResource(SyncAPIResource):
30
+ @cached_property
31
+ def with_raw_response(self) -> ExportsResourceWithRawResponse:
32
+ """
33
+ This property can be used as a prefix for any HTTP method call to return
34
+ the raw response object instead of the parsed content.
35
+
36
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#accessing-raw-response-data-eg-headers
37
+ """
38
+ return ExportsResourceWithRawResponse(self)
39
+
40
+ @cached_property
41
+ def with_streaming_response(self) -> ExportsResourceWithStreamingResponse:
42
+ """
43
+ An alternative to `.with_raw_response` that doesn't eagerly read the response body.
44
+
45
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#with_streaming_response
46
+ """
47
+ return ExportsResourceWithStreamingResponse(self)
48
+
49
+ def create(
50
+ self,
51
+ *,
52
+ resource: Literal[
53
+ "summary",
54
+ "quality",
55
+ "engagement",
56
+ "timeseries",
57
+ "videos",
58
+ "events",
59
+ "views",
60
+ "errors",
61
+ "dimensions",
62
+ "renditions",
63
+ "subtitles",
64
+ "playback_rates",
65
+ "retention",
66
+ ],
67
+ columns: SequenceNotStr[str] | Omit = omit,
68
+ query: ExportQueryParam | Omit = omit,
69
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
70
+ # The extra values given here take precedence over values defined on the client or passed to this method.
71
+ extra_headers: Headers | None = None,
72
+ extra_query: Query | None = None,
73
+ extra_body: Body | None = None,
74
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
75
+ ) -> Export:
76
+ """Create a scoped 256-bit random download token for all matching rows.
77
+
78
+ Requires a
79
+ project private key; read-only keys are allowed. The link expires after 30
80
+ minutes and is invalidated by issuer-key rotation/revocation, project deletion
81
+ or collector restart. No CSV is generated or retained at creation. limit/cursor
82
+ are rejected. Existing query endpoints continue returning JSON. Event CSV files
83
+ contain documented scalar event fields and flat context.\\** columns. Custom
84
+ attributes, nested arrays and historical OTLP payloads are excluded. CSV cells
85
+ never contain JSON objects or arrays; use GET /v1/events for original payloads.
86
+
87
+ Args:
88
+ columns: CSV column names in output order. Omit for all columns. Get the available names
89
+ from GET /v1/exports using the same resource, kind and group_by. Unknown names,
90
+ duplicates and empty selections are rejected.
91
+
92
+ extra_headers: Send extra headers
93
+
94
+ extra_query: Add additional query parameters to the request
95
+
96
+ extra_body: Add additional JSON properties to the request
97
+
98
+ timeout: Override the client-level default timeout for this request, in seconds
99
+ """
100
+ return self._post(
101
+ "/v1/exports",
102
+ body=maybe_transform(
103
+ {
104
+ "resource": resource,
105
+ "columns": columns,
106
+ "query": query,
107
+ },
108
+ export_create_params.ExportCreateParams,
109
+ ),
110
+ options=make_request_options(
111
+ extra_headers=extra_headers,
112
+ extra_query=extra_query,
113
+ extra_body=extra_body,
114
+ timeout=timeout,
115
+ security={"secret_key": True},
116
+ ),
117
+ cast_to=Export,
118
+ )
119
+
120
+ def download(
121
+ self,
122
+ token: str,
123
+ *,
124
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
125
+ # The extra values given here take precedence over values defined on the client or passed to this method.
126
+ extra_headers: Headers | None = None,
127
+ extra_query: Query | None = None,
128
+ extra_body: Body | None = None,
129
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
130
+ ) -> str:
131
+ """The token authorizes only its saved project and query.
132
+
133
+ Requires no Authorization
134
+ header and accepts no query parameters. Generate CSV on demand from one read
135
+ snapshot on a dedicated connection; stream with bounded application buffers and
136
+ backpressure. Dataset is selected when the link is opened. Rows are not capped
137
+ by query pagination. Nested metric columns use slash-separated paths. Events
138
+ have documented scalar columns and flat context.\\** columns. Custom attributes,
139
+ nested arrays and historical OTLP payloads are excluded. CSV cells never contain
140
+ JSON objects or arrays. Nulls are empty cells; spreadsheet-formula strings are
141
+ prefixed with an apostrophe. Interrupted or failed downloads terminate the
142
+ stream; retry the full download. No files are retained. Defaults: 2 download
143
+ starts/minute per project with burst capacity 2, one active CSV generation per
144
+ project and four server-wide. Limits are shared across keys and links. Excess
145
+ requests receive 429 with Retry-After instead of queueing. Override limits in
146
+ config.toml [rate_limits]. Link expiry is checked before starting, not during an
147
+ active download. S3 retention/deletion can remove source objects during a
148
+ download.
149
+
150
+ The download URL contains the credential needed for this request. Treat it as a
151
+ secret until it expires. You can call this method without configuring an API key
152
+ on the client.
153
+
154
+ Args:
155
+ extra_headers: Send extra headers
156
+
157
+ extra_query: Add additional query parameters to the request
158
+
159
+ extra_body: Add additional JSON properties to the request
160
+
161
+ timeout: Override the client-level default timeout for this request, in seconds
162
+ """
163
+ if not token:
164
+ raise ValueError(f"Expected a non-empty value for `token` but received {token!r}")
165
+ extra_headers = {"Accept": "text/csv", **(extra_headers or {})}
166
+ return self._get(
167
+ path_template("/v1/exports/{token}", token=token),
168
+ options=make_request_options(
169
+ extra_headers=extra_headers,
170
+ extra_query=extra_query,
171
+ extra_body=extra_body,
172
+ timeout=timeout,
173
+ security={},
174
+ ),
175
+ cast_to=str,
176
+ )
177
+
178
+ def list_columns(
179
+ self,
180
+ *,
181
+ resource: Literal[
182
+ "summary",
183
+ "quality",
184
+ "engagement",
185
+ "timeseries",
186
+ "videos",
187
+ "events",
188
+ "views",
189
+ "errors",
190
+ "dimensions",
191
+ "renditions",
192
+ "subtitles",
193
+ "playback_rates",
194
+ "retention",
195
+ ],
196
+ group_by: Union[
197
+ Literal[
198
+ "browser_name",
199
+ "os_name",
200
+ "device_type",
201
+ "continent",
202
+ "country",
203
+ "city",
204
+ "page_origin",
205
+ "page_path",
206
+ "subtitle_language",
207
+ "playback_rate",
208
+ "video_title",
209
+ "user_id",
210
+ ],
211
+ str,
212
+ ]
213
+ | Omit = omit,
214
+ kind: Literal["summary", "quality", "engagement"] | Omit = omit,
215
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
216
+ # The extra values given here take precedence over values defined on the client or passed to this method.
217
+ extra_headers: Headers | None = None,
218
+ extra_query: Query | None = None,
219
+ extra_body: Body | None = None,
220
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
221
+ ) -> ExportColumns:
222
+ """Discover column names before creating an export.
223
+
224
+ Requires a project private key;
225
+ read-only keys are allowed. kind applies only to timeseries. group_by applies to
226
+ summary, quality and engagement. Date ranges and filters do not change the
227
+ columns.
228
+
229
+ Args:
230
+ resource: Report whose CSV columns to list.
231
+
232
+ group_by: Optional on summary, quality and engagement. Group views by this field on their
233
+ first retained start. Missing, null and nonstring context forms a null group;
234
+ the literal device type unknown stays separate. Groups sort by views descending,
235
+ then value ascending with null first for ties. Pagination is available only with
236
+ group_by. Location uses the first retained start too. City groups use the stored
237
+ name; filter by country to avoid combining names shared by different countries.
238
+ Page groups use the first retained start even if playback continues after
239
+ navigation. Filter by page_origin when grouping page_path to distinguish
240
+ identical paths on different sites. video_title groups by the title on each
241
+ view's first retained start, so a renamed video counts each view under the title
242
+ it started with. user_id groups by the user ID on each view's first retained
243
+ start. Use custom.<key>, such as custom.plan, to group by a custom dimension;
244
+ views without the key form the null group.
245
+
246
+ kind: Metric set for every time bucket. Uses the same calculations and sample counts
247
+ as the corresponding totals route.
248
+
249
+ extra_headers: Send extra headers
250
+
251
+ extra_query: Add additional query parameters to the request
252
+
253
+ extra_body: Add additional JSON properties to the request
254
+
255
+ timeout: Override the client-level default timeout for this request, in seconds
256
+ """
257
+ return self._get(
258
+ "/v1/exports",
259
+ options=make_request_options(
260
+ extra_headers=extra_headers,
261
+ extra_query=extra_query,
262
+ extra_body=extra_body,
263
+ timeout=timeout,
264
+ query=maybe_transform(
265
+ {
266
+ "resource": resource,
267
+ "group_by": group_by,
268
+ "kind": kind,
269
+ },
270
+ export_list_columns_params.ExportListColumnsParams,
271
+ ),
272
+ security={"secret_key": True},
273
+ ),
274
+ cast_to=ExportColumns,
275
+ )
276
+
277
+
278
+ class AsyncExportsResource(AsyncAPIResource):
279
+ @cached_property
280
+ def with_raw_response(self) -> AsyncExportsResourceWithRawResponse:
281
+ """
282
+ This property can be used as a prefix for any HTTP method call to return
283
+ the raw response object instead of the parsed content.
284
+
285
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#accessing-raw-response-data-eg-headers
286
+ """
287
+ return AsyncExportsResourceWithRawResponse(self)
288
+
289
+ @cached_property
290
+ def with_streaming_response(self) -> AsyncExportsResourceWithStreamingResponse:
291
+ """
292
+ An alternative to `.with_raw_response` that doesn't eagerly read the response body.
293
+
294
+ For more information, see https://www.github.com/chunkifydev/chunkify-analytics-python#with_streaming_response
295
+ """
296
+ return AsyncExportsResourceWithStreamingResponse(self)
297
+
298
+ async def create(
299
+ self,
300
+ *,
301
+ resource: Literal[
302
+ "summary",
303
+ "quality",
304
+ "engagement",
305
+ "timeseries",
306
+ "videos",
307
+ "events",
308
+ "views",
309
+ "errors",
310
+ "dimensions",
311
+ "renditions",
312
+ "subtitles",
313
+ "playback_rates",
314
+ "retention",
315
+ ],
316
+ columns: SequenceNotStr[str] | Omit = omit,
317
+ query: ExportQueryParam | Omit = omit,
318
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
319
+ # The extra values given here take precedence over values defined on the client or passed to this method.
320
+ extra_headers: Headers | None = None,
321
+ extra_query: Query | None = None,
322
+ extra_body: Body | None = None,
323
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
324
+ ) -> Export:
325
+ """Create a scoped 256-bit random download token for all matching rows.
326
+
327
+ Requires a
328
+ project private key; read-only keys are allowed. The link expires after 30
329
+ minutes and is invalidated by issuer-key rotation/revocation, project deletion
330
+ or collector restart. No CSV is generated or retained at creation. limit/cursor
331
+ are rejected. Existing query endpoints continue returning JSON. Event CSV files
332
+ contain documented scalar event fields and flat context.\\** columns. Custom
333
+ attributes, nested arrays and historical OTLP payloads are excluded. CSV cells
334
+ never contain JSON objects or arrays; use GET /v1/events for original payloads.
335
+
336
+ Args:
337
+ columns: CSV column names in output order. Omit for all columns. Get the available names
338
+ from GET /v1/exports using the same resource, kind and group_by. Unknown names,
339
+ duplicates and empty selections are rejected.
340
+
341
+ extra_headers: Send extra headers
342
+
343
+ extra_query: Add additional query parameters to the request
344
+
345
+ extra_body: Add additional JSON properties to the request
346
+
347
+ timeout: Override the client-level default timeout for this request, in seconds
348
+ """
349
+ return await self._post(
350
+ "/v1/exports",
351
+ body=await async_maybe_transform(
352
+ {
353
+ "resource": resource,
354
+ "columns": columns,
355
+ "query": query,
356
+ },
357
+ export_create_params.ExportCreateParams,
358
+ ),
359
+ options=make_request_options(
360
+ extra_headers=extra_headers,
361
+ extra_query=extra_query,
362
+ extra_body=extra_body,
363
+ timeout=timeout,
364
+ security={"secret_key": True},
365
+ ),
366
+ cast_to=Export,
367
+ )
368
+
369
+ async def download(
370
+ self,
371
+ token: str,
372
+ *,
373
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
374
+ # The extra values given here take precedence over values defined on the client or passed to this method.
375
+ extra_headers: Headers | None = None,
376
+ extra_query: Query | None = None,
377
+ extra_body: Body | None = None,
378
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
379
+ ) -> str:
380
+ """The token authorizes only its saved project and query.
381
+
382
+ Requires no Authorization
383
+ header and accepts no query parameters. Generate CSV on demand from one read
384
+ snapshot on a dedicated connection; stream with bounded application buffers and
385
+ backpressure. Dataset is selected when the link is opened. Rows are not capped
386
+ by query pagination. Nested metric columns use slash-separated paths. Events
387
+ have documented scalar columns and flat context.\\** columns. Custom attributes,
388
+ nested arrays and historical OTLP payloads are excluded. CSV cells never contain
389
+ JSON objects or arrays. Nulls are empty cells; spreadsheet-formula strings are
390
+ prefixed with an apostrophe. Interrupted or failed downloads terminate the
391
+ stream; retry the full download. No files are retained. Defaults: 2 download
392
+ starts/minute per project with burst capacity 2, one active CSV generation per
393
+ project and four server-wide. Limits are shared across keys and links. Excess
394
+ requests receive 429 with Retry-After instead of queueing. Override limits in
395
+ config.toml [rate_limits]. Link expiry is checked before starting, not during an
396
+ active download. S3 retention/deletion can remove source objects during a
397
+ download.
398
+
399
+ The download URL contains the credential needed for this request. Treat it as a
400
+ secret until it expires. You can call this method without configuring an API key
401
+ on the client.
402
+
403
+ Args:
404
+ extra_headers: Send extra headers
405
+
406
+ extra_query: Add additional query parameters to the request
407
+
408
+ extra_body: Add additional JSON properties to the request
409
+
410
+ timeout: Override the client-level default timeout for this request, in seconds
411
+ """
412
+ if not token:
413
+ raise ValueError(f"Expected a non-empty value for `token` but received {token!r}")
414
+ extra_headers = {"Accept": "text/csv", **(extra_headers or {})}
415
+ return await self._get(
416
+ path_template("/v1/exports/{token}", token=token),
417
+ options=make_request_options(
418
+ extra_headers=extra_headers,
419
+ extra_query=extra_query,
420
+ extra_body=extra_body,
421
+ timeout=timeout,
422
+ security={},
423
+ ),
424
+ cast_to=str,
425
+ )
426
+
427
+ async def list_columns(
428
+ self,
429
+ *,
430
+ resource: Literal[
431
+ "summary",
432
+ "quality",
433
+ "engagement",
434
+ "timeseries",
435
+ "videos",
436
+ "events",
437
+ "views",
438
+ "errors",
439
+ "dimensions",
440
+ "renditions",
441
+ "subtitles",
442
+ "playback_rates",
443
+ "retention",
444
+ ],
445
+ group_by: Union[
446
+ Literal[
447
+ "browser_name",
448
+ "os_name",
449
+ "device_type",
450
+ "continent",
451
+ "country",
452
+ "city",
453
+ "page_origin",
454
+ "page_path",
455
+ "subtitle_language",
456
+ "playback_rate",
457
+ "video_title",
458
+ "user_id",
459
+ ],
460
+ str,
461
+ ]
462
+ | Omit = omit,
463
+ kind: Literal["summary", "quality", "engagement"] | Omit = omit,
464
+ # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
465
+ # The extra values given here take precedence over values defined on the client or passed to this method.
466
+ extra_headers: Headers | None = None,
467
+ extra_query: Query | None = None,
468
+ extra_body: Body | None = None,
469
+ timeout: float | httpx.Timeout | None | NotGiven = not_given,
470
+ ) -> ExportColumns:
471
+ """Discover column names before creating an export.
472
+
473
+ Requires a project private key;
474
+ read-only keys are allowed. kind applies only to timeseries. group_by applies to
475
+ summary, quality and engagement. Date ranges and filters do not change the
476
+ columns.
477
+
478
+ Args:
479
+ resource: Report whose CSV columns to list.
480
+
481
+ group_by: Optional on summary, quality and engagement. Group views by this field on their
482
+ first retained start. Missing, null and nonstring context forms a null group;
483
+ the literal device type unknown stays separate. Groups sort by views descending,
484
+ then value ascending with null first for ties. Pagination is available only with
485
+ group_by. Location uses the first retained start too. City groups use the stored
486
+ name; filter by country to avoid combining names shared by different countries.
487
+ Page groups use the first retained start even if playback continues after
488
+ navigation. Filter by page_origin when grouping page_path to distinguish
489
+ identical paths on different sites. video_title groups by the title on each
490
+ view's first retained start, so a renamed video counts each view under the title
491
+ it started with. user_id groups by the user ID on each view's first retained
492
+ start. Use custom.<key>, such as custom.plan, to group by a custom dimension;
493
+ views without the key form the null group.
494
+
495
+ kind: Metric set for every time bucket. Uses the same calculations and sample counts
496
+ as the corresponding totals route.
497
+
498
+ extra_headers: Send extra headers
499
+
500
+ extra_query: Add additional query parameters to the request
501
+
502
+ extra_body: Add additional JSON properties to the request
503
+
504
+ timeout: Override the client-level default timeout for this request, in seconds
505
+ """
506
+ return await self._get(
507
+ "/v1/exports",
508
+ options=make_request_options(
509
+ extra_headers=extra_headers,
510
+ extra_query=extra_query,
511
+ extra_body=extra_body,
512
+ timeout=timeout,
513
+ query=await async_maybe_transform(
514
+ {
515
+ "resource": resource,
516
+ "group_by": group_by,
517
+ "kind": kind,
518
+ },
519
+ export_list_columns_params.ExportListColumnsParams,
520
+ ),
521
+ security={"secret_key": True},
522
+ ),
523
+ cast_to=ExportColumns,
524
+ )
525
+
526
+
527
+ class ExportsResourceWithRawResponse:
528
+ def __init__(self, exports: ExportsResource) -> None:
529
+ self._exports = exports
530
+
531
+ self.create = to_raw_response_wrapper(
532
+ exports.create,
533
+ )
534
+ self.download = to_raw_response_wrapper(
535
+ exports.download,
536
+ )
537
+ self.list_columns = to_raw_response_wrapper(
538
+ exports.list_columns,
539
+ )
540
+
541
+
542
+ class AsyncExportsResourceWithRawResponse:
543
+ def __init__(self, exports: AsyncExportsResource) -> None:
544
+ self._exports = exports
545
+
546
+ self.create = async_to_raw_response_wrapper(
547
+ exports.create,
548
+ )
549
+ self.download = async_to_raw_response_wrapper(
550
+ exports.download,
551
+ )
552
+ self.list_columns = async_to_raw_response_wrapper(
553
+ exports.list_columns,
554
+ )
555
+
556
+
557
+ class ExportsResourceWithStreamingResponse:
558
+ def __init__(self, exports: ExportsResource) -> None:
559
+ self._exports = exports
560
+
561
+ self.create = to_streamed_response_wrapper(
562
+ exports.create,
563
+ )
564
+ self.download = to_streamed_response_wrapper(
565
+ exports.download,
566
+ )
567
+ self.list_columns = to_streamed_response_wrapper(
568
+ exports.list_columns,
569
+ )
570
+
571
+
572
+ class AsyncExportsResourceWithStreamingResponse:
573
+ def __init__(self, exports: AsyncExportsResource) -> None:
574
+ self._exports = exports
575
+
576
+ self.create = async_to_streamed_response_wrapper(
577
+ exports.create,
578
+ )
579
+ self.download = async_to_streamed_response_wrapper(
580
+ exports.download,
581
+ )
582
+ self.list_columns = async_to_streamed_response_wrapper(
583
+ exports.list_columns,
584
+ )