# LIVE shop info — `GET /v1/shop/live-room`

> Commerce info for a LIVE room.

- **Canonical URL:** https://api.tikultra.com/v1/shop/live-room
- **Docs Reference:** https://tikultra.com/docs/api/shop-live-room
- **Raw Markdown:** https://tikultra.com/docs/md/api/shop-live-room
- **Family:** TikTok Shop
- **Execution Pool:** Managed Guest Pool · LeanPool — Runs on Tikultra’s warm Guest Mobile Pool (LeanPool)
- **Plan Access:** Every plan
- **Cost:** 25 credits (`0` credits on any failed call)
- **Upstream Mobile Path(s):** `/aweme/v1/oec/live/room/common_info`

## What this endpoint does

Commerce info for a LIVE room. The gateway dispatches `/aweme/v1/oec/live/room/common_info` over HTTP/2 with native mobile TLS/ALPN fingerprints and full `X-Argus`, `X-Ladon`, `X-Gorgon`, and `X-Khronos` headers, then normalizes the protobuf/JSON payload.

- Zero caller credentials needed. Pass optional os, app_flavour, app_version, region, and city parameters to pin exact client and geographic egress.
- Predictable billing: 25 cr on HTTP 200; upstream 5xx, rate-limit 429, and validation 4xx responses always charge 0 credits.
- Client matrix support: override `os`, `app_flavour` (8 apps, 50+ builds), `region` (11+ countries), and `city` (84 cities) per call.

### Execution pool & account boundary

No account_id or login session is required. The gateway selects a bootstrapped, MSSDK-attested mobile guest context matching your requested (os, app_flavour, app_version, region, city), signs the wire request in 0.25 ms p50, and decodes the upstream response to JSON. Zero caller credentials needed. Pass optional os, app_flavour, app_version, region, and city parameters to pin exact client and geographic egress.

## Authorization & parameters

- Header `x-api-key` (`string`, **required**): Your Tikultra API key.

| Parameter | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `room_id` | `string` | yes | The numeric LIVE room ID. | `7707202762026535693` |

## What it returns

Returns `200 OK` `application/json` decoded from `/aweme/v1/oec/live/room/common_info`. Field names (`aweme_id`, `uid`, `sec_uid`, `unique_id`, `room_id`, `product_id`) are consistent across all 200+ endpoints so outputs pipe directly into follow-up calls. If TikTok returns an upstream timeout, empty challenge, or 5xx error, the gateway surfaces a structured error `code` and sets `x-credits-cost: 0`.

### Billing & telemetry headers on every response

- `x-credits-cost`: Exact credits billed for this call (25 on 200 OK; always 0 on failed calls).
- `x-credits-tier`: Pricing tier bucket (premium).
- `x-credits-remaining`: Live remaining credit balance on your API key after this response.

### Key decoded response fields

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | `number` | Upstream mobile status code (`0` indicates clean mobile execution). |
| `room_id` | `string` | 64-bit LIVE broadcast room identifier. |
| `has_commerce_bag` | `boolean` | Decoded `has_commerce_bag` value returned from /aweme/v1/oec/live/room/common_info. |
| `product_count` | `number` | Decoded `product_count` value returned from /aweme/v1/oec/live/room/common_info. |
| `seller_id` | `string` | Decoded `seller_id` value returned from /aweme/v1/oec/live/room/common_info. |
| `gmv_tier` | `string` | Decoded `gmv_tier` value returned from /aweme/v1/oec/live/room/common_info. |
| `atmosphere_tags` | `string[]` | Decoded list of `atmosphere_tags` records (2 shown in sample). |
| `log_pb` | `object` | Upstream request trace (`impr_id`) for protocol auditing. |

## How to use it: TikTok Shop SDUI Product Spy, Visual Search & Affiliate Discovery

Search products by keyword or photo, decode the complete mobile SDUI product detail tree (SKUs, stock, vouchers, logistics), and audit sellers & showcases.

1. **Discover products via keyword, browse, or photo** — [`GET /v1/shop/search`](https://tikultra.com/docs/api/shop-search) (25 cr): Search Shop via GET /v1/shop/search, run an organic browse sequence (/v1/shop/browse), or reverse-search an image (/v1/vision/ecom-search).
2. **Decode full mobile SDUI product page** — [`GET /v1/shop/product-page`](https://tikultra.com/docs/api/shop-product-page) (25 cr): Call GET /v1/shop/product-page to get every SKU price, inventory count, shipping promise, voucher, and seller trust score.
3. **Audit verified buyer reviews & seller catalog** — [`GET /v1/shop/reviews`](https://tikultra.com/docs/api/shop-reviews) (25 cr): Paginate buyer reviews (/v1/shop/reviews, /seller/reviews), full seller catalogs (/v1/shop/seller), and creator showcases (/v1/shop/showcase).
4. **LIVE shop info** **(THIS ENDPOINT)** — [`GET /v1/shop/live-room`](https://tikultra.com/docs/api/shop-live-room) (25 cr): Commerce info for a LIVE room. (GET /v1/shop/live-room).
5. **Inspect pinned LIVE shopping bags** *(optional)* — [`GET /v1/shop/live-bag`](https://tikultra.com/docs/api/live-bag) (25 cr): Monitor flash deals and room sales velocity in active streams via GET /v1/shop/live-bag and /v1/video/anchors.

> **Agent Tip:** Always pass region (e.g., US, GB, MY, TH, VN, PH) on Shop calls because TikTok Shop catalogs, currencies, and SDUI trees are strictly storefront-scoped.

## Code examples (cURL, TypeScript SDK, Python SDK)

### TypeScript SDK
```ts
import { TikUltra } from 'tikultra'

const client = new TikUltra({ apiKey: process.env.TIKULTRA_KEY })

const res = await client.request('GET', '/v1/shop/live-room', { params: { room_id: '7707202762026535693' } })
console.log(res.creditsCost, res.data)
```

### Python SDK
```python
import os
from tikultra import TikUltra

with TikUltra(api_key=os.environ["TIKULTRA_KEY"]) as client:
    res = client.request("GET", "/v1/shop/live-room", params={
        "room_id": "7707202762026535693",
    })
    print(res.credits_cost, res.data)
```

### cURL
```bash
curl -G https://api.tikultra.com/v1/shop/live-room \
  -H "x-api-key: $TIKULTRA_KEY" \
  --data-urlencode "room_id=7707202762026535693"
```

### Python (HTTP)
```python
import os, requests

r = requests.get(
    "https://api.tikultra.com/v1/shop/live-room",
    params={"room_id": "7707202762026535693"},
    headers={"x-api-key": os.environ["TIKULTRA_KEY"]},
)
print(r.headers["x-credits-cost"], r.json())
```

### JavaScript
```bash
const url = new URL('https://api.tikultra.com/v1/shop/live-room')
url.search = new URLSearchParams({ room_id: '7707202762026535693' }).toString()

const res = await fetch(url, { headers: { 'x-api-key': process.env.TIKULTRA_KEY } })
console.log(res.headers.get('x-credits-cost'), await res.json())
```

## Sample 200 JSON response

```json
{
  "status_code": 0,
  "room_id": "7707202762026535693",
  "has_commerce_bag": true,
  "product_count": 8,
  "seller_id": "7495298225862576264",
  "gmv_tier": "high_velocity",
  "atmosphere_tags": [
    "Free shipping",
    "120 sold in LIVE"
  ],
  "log_pb": {
    "impr_id": "202611120200419F8E7D6C5B4A3210"
  }
}
```