> ## Documentation Index > Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # TikTok Shop LIVE Streams > One row per LIVE stream with GMV totals and engagement metrics for the date range. Ordered by GMV descending (no sort parameter). The *_amount metric fields (gpm_amount, aov_amount, average_gmv_per_customer_amount) are integer cents. Lists LIVE streams for your TikTok Shop — one row per LIVE with GMV totals plus the full set of LIVE engagement metrics (viewers, impressions, click-through rates, GPM) for the requested date range. This is the same data as the **Lives** tab of the TikTok Shop store page, with every filter the dashboard offers. ## Response Fields Each LIVE row contains: | Field | Type | Description | | ------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------- | | `id` | Integer | Internal snapshot id | | `external_id` | String | TikTok LIVE id | | `external_creator_id` | String \| null | TikTok creator id (oecuid) of the host | | `external_product_id` | String \| null | Featured product id | | `title` / `truncated_title` | String | LIVE title (full / truncated) | | `duration` | String | Display string of the LIVE start/end time | | `start_time` / `end_time` | String \| null | LIVE start/end (ISO 8601) | | `product` | Object \| null | Featured product `{ id, title, image_url }` | | `affiliate_*` / `connected_account` | Mixed | Growi creator info (see Creators endpoint) | | `total_gmv` | Number | GMV in display currency units | | `total_units_sold` | Integer | Items sold | | `total_sku_orders` | Integer | SKU orders | | `total_commission` | Number | Estimated commission | | `total_refunded_amount` | Number | Refunded amount | | `total_items_refunded` | Integer | Items refunded | | `*_formatted` | String | Display-string variant of every metric above | | `gpm_amount` | Integer | GMV per mille, **integer cents** | | `aov_amount` | Integer | Average order value, **integer cents** | | `average_gmv_per_customer_amount` | Integer | **Integer cents** | | `average_viewing_duration` | String \| null | e.g. `"1m 32s"` | | `unique_viewer_count` / `impression_count` / `like_count` / `comment_count` / `share_count` | Integer | Engagement counts | | `engagement_rate` / `tap_through_rate` / `live_product_click_through_rate` | String \| null | Rate display strings | | `live_product_impressions_count` / `product_clicks_count` / `product_sold_count` | Integer | Product funnel counts | The response envelope is `{ data, meta, additional_data }` (see the Creators endpoint for the envelope shape). ## Request Parameters | Parameter | Type | Description | Required | Default | | ---------------------- | ------- | ----------------------------------------------------- | -------- | ------- | | `start_date` | String | Start of the GMV date range (ISO 8601, `YYYY-MM-DD`) | Yes | — | | `end_date` | String | End of the GMV date range (ISO 8601, `YYYY-MM-DD`) | Yes | — | | `page` | Integer | Page number | No | 1 | | `per_page` | Integer | Results per page (max 100) | No | 20 | | `search` | String | Free-text search | No | — | | `campaign_id` | Integer | Filter to a campaign or contract in your organization | No | — | | `creator_id` | Integer | Filter to a single Growi creator (user id) | No | — | | `external_creator_id` | String | Filter to a single TikTok creator (oecuid) | No | — | | `connected_account_id` | Integer | Filter by connected social account id | No | — | | `platform` | String | `growi`, `all`, or `non_growi` | No | `growi` | | `gmv_min` / `gmv_max` | Number | GMV range bounds in display currency units | No | — | | `organization_id` | Integer | Narrow to a child organization | No | — | ## Request Example ```bash theme={null} curl -X GET "https://api.growi.io/api/public/v1/tik_tok_shop/lives?start_date=2026-07-01&end_date=2026-07-31&platform=all" \ -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \ -H "Content-Type: application/json" ``` ## Response Example ```json theme={null} { "data": [ { "id": 55443, "external_id": "7523400011122233344", "external_creator_id": "7495033444...", "title": "Summer restock LIVE 🍑", "truncated_title": "Summer restock LIVE 🍑...", "duration": "July 15, 2026 18:00 - 19:00", "start_time": "2026-07-15T18:00:00Z", "end_time": "2026-07-15T19:00:00Z", "product": { "id": 887766, "title": "Peach Perfect Multivitamin", "image_url": "https://..." }, "affiliate_name": "Jane Creator", "total_gmv": 7500.0, "total_gmv_formatted": "$7,500.00", "total_units_sold": 260, "total_units_sold_formatted": "260", "gpm_amount": 1250, "aov_amount": 2885, "unique_viewer_count": 4300, "impression_count": 15800, "engagement_rate": "8.4%", "tap_through_rate": "3.1%" } ], "meta": { "row_count": 42, "total_pages": 3, "current_page": 1, "next_page": 2, "prev_page": null }, "additional_data": { "total_gmv": 98000.0, "total_units_sold": 3400, "total_sku_orders": 2980, "total_commission": 14700.0, "total_items_refunded": 85, "total_refunded_amount": 2100.0, "currency_symbol": "$", "currency": "usd" } } ``` ## Use Cases * Measuring LIVE selling performance (GMV, GPM, AOV) per stream * Comparing LIVE engagement funnels: impressions → product clicks → sales * Identifying your best LIVE hosts by GMV and unique viewers * Feeding LIVE performance into scheduling and incentive decisions ## Notes * Results are always ordered by GMV descending; there is no sort parameter. * The `total_*` money fields are raw display-currency numbers; the passthrough `*_amount` metrics (`gpm_amount`, `aov_amount`, `average_gmv_per_customer_amount`) are integer cents. * Rate fields (`engagement_rate`, `tap_through_rate`, `live_product_click_through_rate`) are display strings as provided by TikTok Shop. * Requests are rate limited (minimum 2 seconds between requests plus an hourly quota); see the `X-RateLimit-*` response headers. ## OpenAPI ````yaml GET /tik_tok_shop/lives openapi: 3.0.1 info: title: Growi API description: >- API documentation for Growi platform, showcasing the public tracking event endpoint license: name: MIT version: 1.0.0 servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /tik_tok_shop/lives: get: summary: TikTok Shop LIVE Streams description: >- One row per LIVE stream with GMV totals and engagement metrics for the date range. Ordered by GMV descending (no sort parameter). The *_amount metric fields (gpm_amount, aov_amount, average_gmv_per_customer_amount) are integer cents. parameters: - name: start_date in: query required: true schema: type: string format: date description: Start of the GMV date range (ISO 8601, YYYY-MM-DD) example: '2026-07-01' - name: end_date in: query required: true schema: type: string format: date description: End of the GMV date range (ISO 8601, YYYY-MM-DD) example: '2026-07-31' - name: page in: query required: false schema: type: integer default: 1 description: Page number (default 1) - name: per_page in: query required: false schema: type: integer default: 20 maximum: 100 description: 'Results per page: 1-100, default 20' - name: search in: query required: false schema: type: string description: Free-text search - name: campaign_id in: query required: false schema: type: integer description: Filter to a campaign or contract belonging to your organization - name: creator_id in: query required: false schema: type: integer description: Filter to a single Growi creator (user id) - name: platform in: query required: false schema: type: string enum: - growi - all - non_growi default: growi description: >- Data scope: growi (only creators on Growi, default), all (all TikTok Shop data), non_growi (creators not on Growi) - name: organization_id in: query required: false schema: type: integer description: >- Narrow results to a child organization (id) of the API key organization - name: external_creator_id in: query required: false schema: type: string description: Filter to a single TikTok creator by TikTok creator id (oecuid) - name: connected_account_id in: query required: false schema: type: integer description: >- Filter by connected social account id (matches dashboard behavior; prefer external_creator_id) - name: gmv_min in: query required: false schema: type: number description: Minimum GMV in display currency units (e.g. dollars) - name: gmv_max in: query required: false schema: type: number description: Maximum GMV in display currency units (e.g. dollars) responses: '200': description: LIVE streams listed content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/TikTokShopStoreLiveRow' meta: $ref: '#/components/schemas/TikTokShopStoreMeta' additional_data: $ref: '#/components/schemas/TikTokShopStoreTotals' required: - data - meta - additional_data '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Invalid parameters (missing/invalid dates, unknown platform or linked value, foreign campaign_id, no TikTok Shop connected) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TikTokShopStoreLiveRow: type: object properties: id: type: integer external_id: type: string description: TikTok LIVE id external_creator_id: type: string nullable: true external_product_id: type: string nullable: true title: type: string nullable: true truncated_title: type: string duration: type: string description: Display string of the LIVE start/end time start_time: type: string nullable: true description: ISO 8601 end_time: type: string nullable: true description: ISO 8601 product: type: object nullable: true description: Featured product (id, title, image_url) connected_account: type: object properties: id: type: integer nullable: true username: type: string profile_share_url: type: string affiliate_id: type: integer nullable: true description: Growi user id (null if the creator is not on Growi) affiliate_name: type: string affiliate_email: type: string affiliate_avatar_url: type: string total_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_commission: type: number description: Raw amount in display currency units (e.g. dollars) total_commission_formatted: type: string description: Display string (e.g. "$1,234.56") total_refunded_amount: type: number description: Raw amount in display currency units (e.g. dollars) total_refunded_amount_formatted: type: string description: Display string (e.g. "$1,234.56") total_live_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_live_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_product_card_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_product_card_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_units_sold: type: integer total_units_sold_formatted: type: string total_sku_orders: type: integer total_sku_orders_formatted: type: string total_items_refunded: type: integer total_items_refunded_formatted: type: string item_refunded_count: type: integer gpm_amount: type: integer description: GMV per mille, integer cents average_viewing_duration: type: string nullable: true product_sold_count: type: integer average_gmv_per_customer_amount: type: integer description: Integer cents aov_amount: type: integer description: Average order value, integer cents like_count: type: integer live_product_impressions_count: type: integer comment_count: type: integer engagement_rate: type: string nullable: true share_count: type: integer tap_through_rate: type: string nullable: true unique_viewer_count: type: integer live_product_click_through_rate: type: string nullable: true product_clicks_count: type: integer impression_count: type: integer TikTokShopStoreMeta: type: object description: Pagination metadata properties: row_count: type: integer description: Total rows across all pages total_pages: type: integer current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true TikTokShopStoreTotals: type: object description: Raw totals across the full (unpaginated) result set properties: total_gmv: type: number total_units_sold: type: integer total_sku_orders: type: integer total_commission: type: number total_items_refunded: type: integer total_refunded_amount: type: number currency_symbol: type: string currency: type: string nullable: true Error: required: - error - message type: object properties: error: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer ````