ਜਨਤਕ API ਅਤੇ API ਕੁੰਜੀਆਂ

1. ਸੰਖੇਪ

MousePlayer API ਵਰਕਸਪੇਸ ਤੋਂ ਆਪਣੇ ਡੈਸ਼ਬੋਰਡ, ਡਾਟਾ ਵੇਅਰਹਾਊਸ ਜਾਂ ਅੰਦਰੂਨੀ ਟੂਲਾਂ ਵਿੱਚ ਡਾਟਾ ਲੈਣ ਦਿੰਦਾ ਹੈ। ਸੈਸ਼ਨਾਂ ਨਾਲ ਗਾਹਕ ID ਜੋੜਨ (identify, ਲਿਖਣ ਦਾਇਰੇ ਦੀ ਕੁੰਜੀ ਚਾਹੀਦੀ ਹੈ, ਕੁੰਜੀ ਦਾਇਰੇ ਵੇਖੋ) ਤੋਂ ਇਲਾਵਾ ਇਹ ਸਿਰਫ਼ ਪੜ੍ਹਨ ਲਈ ਹੈ: API ਰਾਹੀਂ ਡਾਟਾ ਬਦਲਿਆ ਜਾਂ ਮਿਟਾਇਆ ਨਹੀਂ ਜਾ ਸਕਦਾ।

ਮੂਲ URL: https://www.mouseplayer.com/api/v1/
ਸਾਰੇ ਜਵਾਬ JSON ਹਨ।
ਹਰ ਬੇਨਤੀ API ਕੁੰਜੀ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਹੁੰਦੀ ਹੈ ਅਤੇ ਆਪਣੇ ਆਪ ਉਸ ਕੁੰਜੀ ਦੇ ਵਰਕਸਪੇਸ ਤੱਕ ਸੀਮਿਤ ਹੈ — ਇੱਕ ਵਰਕਸਪੇਸ ਦੀ ਕੁੰਜੀ ਦੂਜੇ ਦਾ ਡਾਟਾ ਕਦੇ ਨਹੀਂ ਵੇਖ ਸਕਦੀ, ਗਲਤੀ ਨਾਲ ਵੀ ਨਹੀਂ।
ਪੂਰੀ ਸੈਸ਼ਨ ਰਿਕਾਰਡਿੰਗ (ਮਾਊਸ ਹਿਲਜੁਲ, DOM ਸਨੈਪਸ਼ਾਟ) API ਰਾਹੀਂ ਨਹੀਂ ਦਿੱਤੀ ਜਾਂਦੀ। ਸੈਸ਼ਨ ਮੈਟਾਡਾਟਾ, ਸਫ਼ਾ ਦ੍ਰਿਸ਼, ਆਪਣੇ ਇਵੈਂਟ ਅਤੇ ਸੈਗਮੈਂਟ ਮਿਲਦੇ ਹਨ — ਕੱਚਾ ਰਿਕਾਰਡਿੰਗ ਡਾਟਾ ਇੱਧਰ-ਉੱਧਰ ਭੇਜੇ ਬਿਨਾਂ ਰਿਪੋਰਟਾਂ ਅਤੇ ਡੈਸ਼ਬੋਰਡ ਬਣਾਉਣ ਲਈ ਕਾਫ਼ੀ।

2. ਪ੍ਰਮਾਣੀਕਰਨ

API ਕੁੰਜੀਆਂ ਆਪਣੇ ਖਾਤਾ ਮੀਨੂ ਦੇ ਇਸ ਭਾਗ ਵਿੱਚ ਬਣਾਓ ਅਤੇ ਸੰਭਾਲੋ: API ਕੁੰਜੀਆਂ (/api-keys)। ਸਿਰਫ਼ ਵਰਕਸਪੇਸ ਮਾਲਕ ਅਤੇ ਐਡਮਿਨ ਕੁੰਜੀਆਂ ਬਣਾ ਜਾਂ ਰੱਦ ਕਰ ਸਕਦੇ ਹਨ।

ਕੁੰਜੀ ਗੁਪਤ ਰੱਖੋ। ਇਹ ਵਰਕਸਪੇਸ ਦੀ ਹਰ ਚੀਜ਼ ਪੜ੍ਹਨ ਦਿੰਦੀ ਹੈ। ਪੂਰੀ ਕੁੰਜੀ ਬਣਾਉਣ ਤੋਂ ਤੁਰੰਤ ਬਾਅਦ ਬਿਲਕੁਲ ਇੱਕ ਵਾਰ ਦਿਸਦੀ ਹੈ — ਪਾਸਵਰਡ ਮੈਨੇਜਰ ਜਾਂ ਸੀਕ੍ਰੇਟ ਵਾਲਟ ਵਿੱਚ ਰੱਖੋ। ਗੁਆਚ ਜਾਵੇ ਤਾਂ ਰੱਦ ਕਰਕੇ ਨਵੀਂ ਬਣਾਓ।

ਹਰ ਬੇਨਤੀ ਦੇ ਇਸ ਹੈਡਰ ਵਿੱਚ ਕੁੰਜੀ Bearer ਟੋਕਨ ਵਜੋਂ ਭੇਜੋ: Authorization :

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

ਗੁੰਮ, ਗਲਤ ਰੂਪ ਜਾਂ ਰੱਦ ਕੁੰਜੀਆਂ ਨੂੰ ਇਹ 401 ਜਵਾਬ ਮਿਲਦਾ ਹੈ:

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

ਯੋਜਨਾ ਦੀ ਲੋੜ

REST API ਇਨ੍ਹਾਂ ਯੋਜਨਾਵਾਂ ਦਾ ਹਿੱਸਾ ਹੈ: Business ਅਤੇ Enterprise । ਯੋਜਨਾ ਵਰਕਸਪੇਸ ਦੇ ਮਾਲਕ ਤੋਂ ਲਈ ਜਾਂਦੀ ਹੈ, ਇਸ ਲਈ ਸੱਦੇ ਟੀਮ ਮੈਂਬਰਾਂ ਨੂੰ ਵੀ ਮਿਲਦੀ ਹੈ। ਜਾਂਚ ਹੁੰਦੀ ਹੈ ਹਰ ਬੇਨਤੀ ਉੱਤੇ, ਸਿਰਫ਼ ਕੁੰਜੀ ਬਣਾਉਣ ਵੇਲੇ ਨਹੀਂ — ਵਰਕਸਪੇਸ ਘੱਟ ਯੋਜਨਾ ਵਿੱਚ ਜਾਵੇ ਤਾਂ ਮੌਜੂਦਾ ਕੁੰਜੀਆਂ ਰੁਕ ਕੇ ਇਹ ਦਿੰਦੀਆਂ ਹਨ: 403।

ਕੁੰਜੀ ਦਾਇਰੇ

ਹਰ ਕੁੰਜੀ ਆਪਣੇ ਅਗੇਤਰ ਵਿੱਚ ਦਾਇਰਾ ਰੱਖਦੀ ਹੈ, ਇਸ ਲਈ ਵੇਖ ਕੇ ਹੀ ਕੰਮ ਪਤਾ ਲੱਗ ਸਕਦਾ ਹੈ — ਇਸ ਵਿੱਚ, .env, ਟਿਕਟ ਜਾਂ ਟਰਮੀਨਲ ਵਿੱਚ।

ਅਗੇਤਰ	ਅਰਥ
`mp_ro_`	ਸਿਰਫ਼ ਪੜ੍ਹਨਾ। ਪ੍ਰੋਜੈਕਟ, ਸੈਸ਼ਨ, ਇਵੈਂਟ ਅਤੇ ਸੈਗਮੈਂਟ ਪੜ੍ਹਦੀ ਹੈ। ਕੁਝ ਬਦਲ ਨਹੀਂ ਸਕਦੀ।
`mp_rw_`	ਪੜ੍ਹਨਾ ਅਤੇ ਲਿਖਣਾ। ਉੱਪਰਲਾ ਸਭ ਅਤੇ identify ਐਂਡਪੁਆਇੰਟ ਰਾਹੀਂ ਗਾਹਕ ID ਜੋੜਨਾ।

ਕੁੰਜੀ ਬਣਾਉਣ ਵੇਲੇ ਦਾਇਰਾ ਚੁਣੋ; ਮੂਲ ਸਿਰਫ਼ ਪੜ੍ਹਨਾ ਹੈ। ਲਿਖਣ ਵਾਲੇ ਐਂਡਪੁਆਇੰਟ ਉੱਤੇ ਪੜ੍ਹਨ ਦੀ ਕੁੰਜੀ ਵਰਤਣ ਨਾਲ ਇਹ ਆਉਂਦਾ ਹੈ: 403 ਨਾਲ ਸੁਨੇਹਾ ਜੋ ਕੁੰਜੀ ਦੀ ਕਿਸਮ ਅਤੇ ਐਂਡਪੁਆਇੰਟ ਦੀ ਲੋੜ ਦੱਸਦਾ ਹੈ। ਦਾਇਰਾ ਬਾਅਦ ਨਹੀਂ ਬਦਲ ਸਕਦਾ — ਨਵੀਂ ਕੁੰਜੀ ਬਣਾਓ ਅਤੇ ਪੁਰਾਣੀ ਰੱਦ ਕਰੋ।

3. ਬੇਨਤੀ ਦਰ ਹੱਦਾਂ

ਹਰ API ਕੁੰਜੀ ਲਈ ਹੱਦ ਹੈ ਹਰ ਮਿੰਟ 60 ਬੇਨਤੀਆਂ, ਚੱਲਦੇ ਸਮਾਂ-ਝਰੋਖੇ ਵਿੱਚ ਟਰੈਕ ਹੁੰਦੀ ਹੈ। ਵੱਧ ਜਾਣ ਉੱਤੇ ਬੇਨਤੀਆਂ ਨੂੰ ਇਹ 429 ਜਵਾਬ ਮਿਲਦਾ ਹੈ, ਝਰੋਖਾ ਸਾਫ਼ ਹੋਣ ਤੱਕ:

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

ਵੱਧ ਹੱਦ ਵਾਲਾ ਕੁਝ ਬਣਾ ਰਹੇ ਹੋ? ਇਸ ਰਾਹੀਂ ਸੰਪਰਕ ਕਰੋ: ਸਹਾਇਤਾ ਅਤੇ ਆਪਣੀ ਵਰਤੋਂ ਦੱਸੋ।

4. ਐਂਡਪੁਆਇੰਟ

GET/api/v1/projects

ਵਰਕਸਪੇਸ ਦਾ ਹਰ ਪ੍ਰੋਜੈਕਟ (ਟਰੈਕ ਪ੍ਰਾਪਰਟੀ) ਸੂਚੀਬੱਧ ਕਰਦਾ ਹੈ।

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

GET/api/v1/projects/{channelid}/sessions

ਪ੍ਰੋਜੈਕਟ ਦੇ ਰਿਕਾਰਡ ਵਿਜ਼ਟਰ ਸੈਸ਼ਨ ਸੂਚੀਬੱਧ ਕਰਦਾ ਹੈ, ਨਵੇਂ ਪਹਿਲਾਂ। ਸਫ਼ਿਆਂ ਵਿੱਚ ਵੰਡੇ।

ਕਵੇਰੀ ਪੈਰਾਮੀਟਰ	ਵੇਰਵਾ
`page`	ਸਫ਼ਾ ਨੰਬਰ, ਮੂਲ `1`।
`per_page`	ਹਰ ਸਫ਼ੇ ਦੇ ਨਤੀਜੇ, ਮੂਲ `25`, ਵੱਧ ਤੋਂ ਵੱਧ `100`।
`since`	ਸਿਰਫ਼ ਇਸ ਤਾਰੀਖ ਨੂੰ ਜਾਂ ਬਾਅਦ ਸ਼ੁਰੂ ਸੈਸ਼ਨ (`YYYY-MM-DD`)।
`until`	ਸਿਰਫ਼ ਇਸ ਤਾਰੀਖ ਨੂੰ ਜਾਂ ਪਹਿਲਾਂ ਸ਼ੁਰੂ ਸੈਸ਼ਨ।

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

ਇੱਕ ਸੈਸ਼ਨ ਦਾ ਮੈਟਾਡਾਟਾ ਅਤੇ ਸਫ਼ਾ ਦ੍ਰਿਸ਼। ਪੂਰਾ ਰਿਕਾਰਡਿੰਗ ਡਾਟਾ ਜਾਣਬੁੱਝ ਕੇ ਬਾਹਰ — ਉਸ ਲਈ ਡੈਸ਼ਬੋਰਡ ਪਲੇਅਰ ਵਰਤੋ।

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

GET/api/v1/sessions/{session_id}/events

ਸੈਸ਼ਨ ਦੌਰਾਨ ਚੱਲੇ ਆਪਣੇ ਇਵੈਂਟ (ਉਹੀ ਜੋ ਇਸ ਨਾਲ ਭੇਜਦੇ ਹੋ: mp('event', ...)), ਉਨ੍ਹਾਂ ਦੇ ਪੈਰਾਮੀਟਰਾਂ ਸਮੇਤ।

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

GET/api/v1/projects/{channelid}/segments

ਪ੍ਰੋਜੈਕਟ ਲਈ ਤੈਅ ਵਿਜ਼ਟਰ ਸੈਗਮੈਂਟ ਸੂਚੀਬੱਧ ਕਰਦਾ ਹੈ (ਪ੍ਰੋਜੈਕਟ-ਖ਼ਾਸ ਅਤੇ ਪੂਰੇ ਵਰਕਸਪੇਸ ਵਾਲੇ ਦੋਵੇਂ)।

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. ਆਪਣੇ ਬੈਕਐਂਡ ਤੋਂ ਗਾਹਕ ID ਜੋੜਨਾ

ਬ੍ਰਾਊਜ਼ਰ ਨੂੰ ਅਕਸਰ ਨਹੀਂ ਪਤਾ ਕਿ ਸਾਹਮਣੇ ਕੌਣ ਹੈ। B2B ਉਤਪਾਦ ਵਿੱਚ ਪਛਾਣ ਲੌਗ ਇਨ ਤੋਂ ਬਾਅਦ ਤੈਅ ਹੁੰਦੀ ਹੈ — ਬੈਕਐਂਡ ਵਿੱਚ। ਦੁਕਾਨ ਵਿੱਚ ਆਰਡਰ ਪੁਸ਼ਟੀ ਨਾਲ ਤੈਅ ਹੁੰਦੀ ਹੈ। ਇਹ ਐਂਡਪੁਆਇੰਟ ਇਸੇ ਪਲ ਲਈ ਹੈ।

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID ਫਿਰ ਸੈਸ਼ਨ ਸੂਚੀ ਵਿੱਚ ਦਿਸਦੀ ਅਤੇ ਖੋਜੀ ਜਾ ਸਕਦੀ ਹੈ ਅਤੇ ਇਹ session_identified ਵੈੱਬਹੂਕ ਚੱਲਦਾ ਹੈ — ਇਸੇ ਤਰ੍ਹਾਂ CRM ਤੱਕ ਪਹੁੰਚਦੀ ਹੈ।

ਉਹੀ ID ਨਾਲ ਦੋ ਵਾਰ ਕਾਲ ਕਰਨਾ ਸੁਰੱਖਿਅਤ ਹੈ। ਜਵਾਬ ਵਿੱਚ ਇਹ ਵਾਪਸ ਆਉਂਦਾ ਹੈ: "changed": false ਅਤੇ ਵੈੱਬਹੂਕ ਨਹੀਂ ਭੇਜਿਆ ਜਾਂਦਾ। ਦੁਹਰਾਇਆ ਆਰਡਰ ਦੂਜਾ ਸੰਭਾਵੀ ਗਾਹਕ ਨਹੀਂ ਬਣਾਉਂਦਾ।

ਸਥਿਤੀ	ਕਦੋਂ
`400`	ਖੇਤਰ ਗੁੰਮ, `user_id` 128 ਅੱਖਰਾਂ ਤੋਂ ਲੰਬਾ ਜਾਂ ਅੰਦਰ ਕੰਟਰੋਲ ਅੱਖਰ। ਕੱਟਣ ਦੀ ਥਾਂ ਰੱਦ ਕਰਦੇ ਹਾਂ — ਚੁੱਪਚਾਪ ਛੋਟੀ ID CRM ਵਿੱਚ ਕਿਸੇ ਨਾਲ ਨਹੀਂ ਮਿਲਦੀ ਪਰ ਸਫਲਤਾ ਵਰਗੀ ਦਿਸਦੀ ਹੈ।
`404`	ਸੈਸ਼ਨ ਮੌਜੂਦ ਨਹੀਂ ਜਾਂ ਤੁਹਾਡੇ ਵਰਕਸਪੇਸ ਦਾ ਨਹੀਂ। ਦੋਵਾਂ ਲਈ ਜਾਣਬੁੱਝ ਕੇ ਇੱਕੋ ਜਵਾਬ।
`403`	ਵਰਕਸਪੇਸ ਯੋਜਨਾ ਵਿੱਚ API ਨਹੀਂ ਹੈ।

6. ਵੈੱਬਹੂਕ: ਦਸਤਖ਼ਤ ਦੀ ਪੁਸ਼ਟੀ

ਹਰ ਪ੍ਰੋਜੈਕਟ ਲਈ ਵੈੱਬਹੂਕ ਇਸ ਹੇਠ ਸੈੱਟ ਹੁੰਦੇ ਹਨ: ਏਕੀਕਰਨ, ਜਿੱਥੇ ਦਸਤਖ਼ਤ ਸੀਕ੍ਰੇਟ ਵੀ ਮਿਲਦਾ ਹੈ। ਹਰ ਡਿਲਿਵਰੀ ਵਿੱਚ ਇਹ ਹੈਡਰ ਹਨ:

ਹੈਡਰ	ਅਰਥ
`X-MousePlayer-Event`	ਇਵੈਂਟ ਨਾਮ, ਜਿਵੇਂ `session_identified`
`X-MousePlayer-Timestamp`	Unix ਸਕਿੰਟ — ਦਸਤਖ਼ਤ ਲਿਖਤ ਦਾ ਹਿੱਸਾ
`X-MousePlayer-Attempt`	ਪਹਿਲੀ ਕੋਸ਼ਿਸ਼ ਉੱਤੇ 1, ਮੁੜ ਕੋਸ਼ਿਸ਼ਾਂ ਉੱਤੇ ਵੱਧ
`X-MousePlayer-Signature`	`sha256=<hex>`

ਦਸਤਖ਼ਤ ਇਸ ਉੱਤੇ HMAC-SHA256 ਹੈ: timestamp + "." + raw body, ਤੁਹਾਡੇ ਪ੍ਰੋਜੈਕਟ ਦੇ ਦਸਤਖ਼ਤ ਸੀਕ੍ਰੇਟ ਨੂੰ ਕੁੰਜੀ ਬਣਾ ਕੇ।

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

ਦਸਤਖ਼ਤ ਕਰੋ ਕੱਚੇ ਮੁੱਖ ਡਾਟੇ ਉੱਤੇ, JSON ਪਾਰਸ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ। ਮੁੜ ਸੀਰੀਅਲਾਈਜ਼ ਕਰਨ ਨਾਲ ਕੁੰਜੀ ਕ੍ਰਮ ਅਤੇ ਖਾਲੀ ਥਾਵਾਂ ਬਦਲਦੀਆਂ ਹਨ ਅਤੇ ਦਸਤਖ਼ਤ ਕਦੇ ਨਹੀਂ ਮਿਲੇਗਾ। ਕੁਝ ਮਿੰਟਾਂ ਤੋਂ ਪੁਰਾਣੀ ਸਮਾਂ-ਮੋਹਰ ਵਾਲਾ ਵੀ ਰੱਦ ਕਰੋ — ਸਮਾਂ-ਮੋਹਰ ਦਾ ਕੰਮ ਇਹੀ ਹੈ।

ਡਿਲਿਵਰੀ ਅਤੇ ਮੁੜ ਕੋਸ਼ਿਸ਼ਾਂ

ਨਾਕਾਮ ਡਿਲਿਵਰੀ ਲਈ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਹੁੰਦੀ ਹੈ: 1 ਮਿੰਟ, 5 ਮਿੰਟ, 15 ਮਿੰਟ, 1 ਘੰਟਾ ਅਤੇ 6 ਘੰਟੇ ਬਾਅਦ, ਫਿਰ ਛੱਡ ਦਿੱਤੀ ਜਾਂਦੀ ਹੈ। 4xx ਇਸ ਕਿਸਮ ਦੇ ਜਵਾਬ, ਇਨ੍ਹਾਂ ਤੋਂ ਇਲਾਵਾ, 408 ਅਤੇ 429 , ਨਹੀਂ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕੀਤੇ ਜਾਂਦੇ — ਉਹ "ਇਸ ਤਰ੍ਹਾਂ ਨਹੀਂ" ਕਹਿੰਦੇ ਹਨ, "ਹੁਣੇ ਨਹੀਂ" ਨਹੀਂ। ਇਹ ਜਵਾਬ ਦਿਓ: 2xx ਜਲਦੀ ਅਤੇ ਕੰਮ ਬਾਅਦ ਕਰੋ; ਡਿਲਿਵਰੀ 10 ਸਕਿੰਟਾਂ ਬਾਅਦ ਸਮਾਂ ਮੁਕਾ ਦਿੰਦੀ ਹੈ।

ਉਪਲਬਧ ਇਵੈਂਟ

ਇਵੈਂਟ	ਕਦੋਂ ਚੱਲਦਾ ਹੈ
`session_identified`	ਸੈਸ਼ਨ ਨੂੰ ਪਹਿਲੀ ਗਾਹਕ ID ਮਿਲਣ ਉੱਤੇ — ਬ੍ਰਾਊਜ਼ਰ ਜਾਂ API ਤੋਂ
`session_ended`	ਇੱਕ ਵਾਰ, ਸੈਸ਼ਨ ਬੰਦ ਹੋਣ ਉੱਤੇ
`goal_reached`	ਹਰ ਸੈਸ਼ਨ ਇੱਕ ਵਾਰ, ਜਦੋਂ ਆਪਣਾ ਇਵੈਂਟ ਕੋਈ ਟੀਚਾ ਪੂਰਾ ਕਰੇ। ਸਿਰਫ਼ “event” ਕਿਸਮ ਦੇ ਟੀਚੇ — URL, ਮਿਆਦ, ਸਫ਼ਾ ਦ੍ਰਿਸ਼ ਅਤੇ ਫਨਲ ਟੀਚੇ ਨਹੀਂ ਜਾਂਚੇ ਜਾਂਦੇ। ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `goal_id`, `goal_name`, `goal_value` ਅਤੇ `currency`।
`high_value_session`	ਕਿਸੇ ਦਿਨ ਵਿਜ਼ਟਰ ਇਸ ਪ੍ਰੋਜੈਕਟ ਦੀ ਮੁੱਲ ਹੱਦ ਪਹਿਲੀ ਵਾਰ ਪਾਰ ਕਰੇ। ਹੱਦ ਤੁਹਾਡੇ ਆਪਣੇ ਸਕੋਰਾਂ ਦੀ ਵੰਡ ਤੋਂ ਨਿਕਲਦੀ ਹੈ (ਪਿਛਲੇ 90 ਦਿਨਾਂ ਦਾ 90ਵਾਂ ਪ੍ਰਤੀਸ਼ਤਕ), ਸਥਿਰ ਅੰਕ ਨਹੀਂ ਅਤੇ ਘੱਟੋ-ਘੱਟ 20 ਵਿਜ਼ਟਰਾਂ ਨੂੰ ਸਕੋਰ ਮਿਲਣ ਤੱਕ ਬਣਦੀ ਹੀ ਨਹੀਂ। ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `visitor_id`, `value_score`, `threshold` ਅਤੇ ਉਸ ਦਿਨ ਦਾ ਸਭ ਤੋਂ ਵੇਖਣ ਯੋਗ ਸੈਸ਼ਨ।
`funnel_dropoff`	ਉਸ ਸੈਸ਼ਨ ਦੇ ਅਖੀਰ ਉੱਤੇ ਜੋ ਕਿਸੇ ਫਨਲ ਵਿੱਚ ਆਇਆ ਪਰ ਪੂਰਾ ਨਹੀਂ ਕੀਤਾ। ਰੁਕਣ ਵਾਲੇ ਕਦਮ ਦਾ ਨਾਮ ਦਿੰਦਾ ਹੈ (`dropped_at`)। ਛੱਡਣਾ ਇਵੈਂਟ ਦੀ ਗੈਰਹਾਜ਼ਰੀ ਹੈ, ਇਸ ਲਈ ਸੈਸ਼ਨ ਮੁੱਕਣ ਤੋਂ ਬਾਅਦ ਹੀ ਪਤਾ ਲੱਗ ਸਕਦਾ ਹੈ। ਫਨਲ ਵਿੱਚ ਕਦੇ ਨਾ ਆਏ ਸੈਸ਼ਨ ਛੱਡਣ ਵਾਲੇ ਨਹੀਂ ਅਤੇ ਇਵੈਂਟ ਨਹੀਂ ਚਲਾਉਂਦੇ।
`high_friction_session`	ਹਰ ਸੈਸ਼ਨ ਇੱਕ ਵਾਰ, ਜਦੋਂ ਰੁਕਾਵਟ ਸਕੋਰ ਪਹਿਲੀ ਵਾਰ ਹੱਦ ਤੱਕ ਪਹੁੰਚੇ (ਮੂਲ 60, ਕੁੱਲ 100 ਵਿੱਚੋਂ)। ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `friction_score`, ਇਸ ਦੇ ਪਿੱਛੇ ਸੰਕੇਤ (`reasons`) ਅਤੇ ਹੱਦ ਪਾਰ ਕਰਨ ਵਾਲਾ ਸੰਕੇਤ (`trigger`)।
`element_broken`	ਇੱਕ ਵਾਰ, ਜਦੋਂ ਟਰੈਕ ਕੀਤੇ ਅੰਗ ਨੂੰ ਕਈ ਦਿਨ ਕਿਸੇ ਜਾਂਚੇ ਸਫ਼ਾ ਦ੍ਰਿਸ਼ ਵਿੱਚ ਕੁਝ ਨਾ ਮਿਲੇ — ਆਮ ਤੌਰ ਉੱਤੇ ਮੁੜ ਲਾਂਚ ਤੋਂ ਬਾਅਦ। ਫਿਰ ਸਿਰਫ਼ ਨਿਸ਼ਾਨ ਦੇ ਮੇਲ ਖਾਣ ਅਤੇ ਮੁੜ ਟੁੱਟਣ ਤੋਂ ਬਾਅਦ ਚੱਲਦਾ ਹੈ। ਇਹ ਇਵੈਂਟ ਕਿਸੇ ਸੈਸ਼ਨ ਦਾ ਨਹੀਂ: `session_id` ਅਤੇ `session_url` ਹਨ `null`, `link_url` ਇਸ ਦੀ ਥਾਂ ਨਿਸ਼ਾਨ ਖੋਲ੍ਹਦਾ ਹੈ ਅਤੇ `subject_id` ਨਿਸ਼ਾਨ ਦਾ ਨਾਮ ਹੈ — ਹਰ ਵਰਜਨ ਲਈ ਉਹੀ, ਤਾਂ ਜੋ ਮੁੜ ਟੁੱਟਦਾ ਨਵਾਂ ਸਿਲੈਕਟਰ ਖੁੱਲ੍ਹੀ ਘਟਨਾ ਨਾਲ ਜੁੜੇ। ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `rule_id`, `rule_name`, `selector`, `page`, `checked_page_views`, `window_days` ਅਤੇ `last_matched`। ਵਿਜ਼ਟਰ ਡਾਟਾ ਨਹੀਂ।
`element_recovered`	ਇਸ ਲਈ ਸਭ ਠੀਕ ਹੋਣ ਦਾ ਸੁਨੇਹਾ: `element_broken`: ਨਿਸ਼ਾਨ ਅਸਲ ਵਿੱਚ ਮੁੜ ਅੰਗ ਲੱਭੇ ਤਾਂ ਇੱਕ ਵਾਰ — ਬਹੁਤ ਘੱਟ ਸਫ਼ਾ ਦ੍ਰਿਸ਼ ਕਾਫ਼ੀ ਨਹੀਂ। ਸਿਰਫ਼ ਤਾਂ ਭੇਜਿਆ ਜੇ `element_broken` ਵੈੱਬਹੂਕ ਰਾਹੀਂ ਗਿਆ ਸੀ ਅਤੇ ਆਪਣਾ ਸਵਿੱਚ ਨਹੀਂ ਹੈ: ਇਸ ਨੂੰ ਸਬਸਕ੍ਰਾਈਬ ਕਰਨਾ, `element_broken` , ਇਹ ਵੀ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਉਹੀ `subject_id`, ਤਾਂ ਜੋ PagerDuty ਘਟਨਾ ਹੱਲ ਕਰੇ ਅਤੇ Opsgenie ਚੇਤਾਵਨੀ ਬੰਦ ਕਰੇ। ਵਾਧੂ ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `matched_page_views` ਅਤੇ `checked_page_views` ।
`anomaly_detected`	ਦਿਨ ਵਿੱਚ ਇੱਕ ਵਾਰ, ਜਦੋਂ ਕੱਲ੍ਹ ਪਿਛਲੇ 28 ਦਿਨਾਂ ਤੋਂ ਸਪਸ਼ਟ ਵੱਖਰਾ ਹੋਵੇ: ਬਹੁਤ ਘੱਟ ਜਾਂ ਵੱਧ ਸੈਸ਼ਨ, ਘਟੀ ਟੀਚਾ ਦਰ, ਵੱਧ ਰੁਕਾਵਟ ਜਾਂ JS ਗਲਤੀਆਂ ਵਾਲੇ ਸੈਸ਼ਨ। ਉਹੀ ਮਾਪ ਅਤੇ ਦਿਸ਼ਾ ਇੱਕ ਹਫ਼ਤਾ ਚੁੱਪ ਰਹਿੰਦੇ ਹਨ (ਬਦਲਣ ਯੋਗ)। ਇਹ ਇਵੈਂਟ ਕਿਸੇ ਸੈਸ਼ਨ ਦਾ ਨਹੀਂ: `session_id` ਅਤੇ `session_url` ਹਨ `null`, `link_url` ਪ੍ਰੋਜੈਕਟ ਸੰਖੇਪ ਖੋਲ੍ਹਦਾ ਹੈ ਅਤੇ `subject_id` ਮਾਪ, ਦਿਸ਼ਾ ਅਤੇ ਦਿਨ ਦਾ ਨਾਮ ਦਿੰਦਾ ਹੈ। ਇਹ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ: `metric` (`sessions`, `goal_rate`, `friction_rate`, `js_error_rate`, `lcp_p75`, `inp_p75`, `cls_p75`), `direction`, `day`, `value`, `expected`, `sessions`, `robust_z`, `z_score` ਅਤੇ ਪੜ੍ਹਨ ਯੋਗ `summary` ਅਤੇ `hint`। ਵਿਜ਼ਟਰ ਡਾਟਾ ਨਹੀਂ। Web Vitals ਲਈ, `measurements` ਇਸ ਦੀ ਥਾਂ ਆਉਂਦਾ ਹੈ: `sessions` ਅਤੇ `page` (ਪੂਰੀ ਸਾਈਟ ਲਈ ਖਾਲੀ) ਅਤੇ `device` (`desktop` ਜਾਂ `mobil`) ਦੱਸਦੇ ਹਨ ਕਿ ਕਿੱਥੇ ਹੋਇਆ; `link_url` ਫਿਰ Web Vitals ਟੈਬ ਖੋਲ੍ਹਦਾ ਹੈ।
`rage_click`	ਪਛਾਣੇ ਗੁੱਸੇ ਵਾਲੇ ਕਲਿੱਕ ਉੱਤੇ
`error_detected`	ਫਰੰਟਐਂਡ ਅਪਵਾਦ ਉੱਤੇ
`ce`	ਆਪਣੇ ਇਵੈਂਟਾਂ ਲਈ ਸਮੂਹਿਕ ਸਬਸਕ੍ਰਿਪਸ਼ਨ। ਇਸ ਵਿੱਚ ਨਹੀਂ ਆਉਂਦੇ ਉੱਪਰਲੇ ਇਵੈਂਟ — ਉਨ੍ਹਾਂ ਦੇ ਆਪਣੇ ਸਵਿੱਚ ਹਨ।

7. ਗਲਤੀਆਂ & ਸਥਿਤੀ ਕੋਡ

ਸਥਿਤੀ	ਅਰਥ
`200`	ਸਫਲਤਾ।
`401`	ਗੁੰਮ, ਗਲਤ ਰੂਪ ਜਾਂ ਰੱਦ API ਕੁੰਜੀ।
`404`	ਮੰਗਿਆ ਪ੍ਰੋਜੈਕਟ ਜਾਂ ਸੈਸ਼ਨ ਮੌਜੂਦ ਨਹੀਂ ਜਾਂ ਵਰਕਸਪੇਸ ਦਾ ਨਹੀਂ ਹੈ।
`429`	ਬੇਨਤੀ ਦਰ ਹੱਦ ਪਾਰ — ਇਸ ਕੁੰਜੀ ਨਾਲ ਹਰ ਮਿੰਟ 60 ਤੋਂ ਵੱਧ ਬੇਨਤੀਆਂ ਭੇਜ ਰਹੇ ਹੋ।
`403`	ਵਰਕਸਪੇਸ ਯੋਜਨਾ ਵਿੱਚ REST API ਨਹੀਂ ਹੈ। ਸੁਨੇਹਾ ਲੋੜੀਂਦੀ ਅਤੇ ਮੌਜੂਦਾ ਦੋਵੇਂ ਯੋਜਨਾਵਾਂ ਦੱਸਦਾ ਹੈ।

8. ਸੁਰੱਖਿਆ ਨੋਟ

ਪੜ੍ਹਨ ਵਾਲੀਆਂ ਕੁੰਜੀਆਂ (mp_ro_) ਕੁਝ ਨਹੀਂ ਬਦਲ ਸਕਦੀਆਂ। ਲਿਖਣ ਵਾਲੀਆਂ (mp_rw_) ਸਿਰਫ਼ ਗਾਹਕ ID ਜੋੜ ਸਕਦੀਆਂ ਹਨ; ਕੋਈ ਕੁੰਜੀ ਡਾਟਾ ਮਿਟਾ ਜਾਂ ਕੱਚਾ ਰਿਕਾਰਡਿੰਗ ਡਾਟਾ ਨਿਰਯਾਤ ਨਹੀਂ ਕਰ ਸਕਦੀ।
ਹਰ ਬੇਨਤੀ ਆਪਣੇ ਆਪ ਕੁੰਜੀ ਦੇ ਆਪਣੇ ਵਰਕਸਪੇਸ ਤੱਕ ਸੀਮਿਤ ਹੈ — ਵੱਖਰੀ ਵਰਕਸਪੇਸ ID ਦੇ ਕੇ ਕਿਸੇ ਹੋਰ ਦਾ ਡਾਟਾ ਵੇਖਣ ਦਾ ਰਸਤਾ ਨਹੀਂ।
ਕਿਸੇ ਵੀ ਵੇਲੇ ਇੱਥੋਂ ਕੁੰਜੀ ਰੱਦ ਕਰੋ: /api-keys; ਰੱਦ ਕਰਨਾ ਤੁਰੰਤ ਲਾਗੂ ਹੁੰਦਾ ਹੈ।
API ਕੁੰਜੀ ਨੂੰ ਪਾਸਵਰਡ ਵਾਂਗ ਮੰਨੋ। ਗਲਤੀ ਨਾਲ ਜਨਤਕ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ ਕਮਿਟ ਕਰੋ ਤਾਂ ਤੁਰੰਤ ਰੱਦ ਕਰਕੇ ਨਵੀਂ ਬਣਾਓ।

ਸੀਮਿਤ ਇਵੈਂਟ ਸਫ਼ੇ (API v1, 14 ਅਕਤੂਬਰ 2026)

GET /api/v1/sessions/{session_id}/events ਮੂਲ ਰੂਪ ਵਿੱਚ ਵੱਧ ਤੋਂ ਵੱਧ 100 ਇਵੈਂਟ ਦਿੰਦਾ ਹੈ। per_page ਨੂੰ 1 ਤੋਂ 100 ਤੱਕ ਪੂਰਨ ਅੰਕ ਰੱਖੋ। ਅਗਲੀ ਬੇਨਤੀ ਵਿੱਚ cursor ਬਿਨਾਂ ਬਦਲੇ ਭੇਜ ਕੇ pagination.next_cursor ਦੀ ਪਾਲਣਾ ਕਰੋ; ਉਹੀ ਸੈਸ਼ਨ ਅਤੇ ਵਰਕਸਪੇਸ ਰੱਖੋ। ਇਵੈਂਟ created_at ਅਤੇ event_id ਅਨੁਸਾਰ ਕ੍ਰਮਬੱਧ ਹਨ। ਕਰਸਰ ਦਸਤਖ਼ਤ ਕੀਤੇ ਅਤੇ ਉਸ ਸੈਸ਼ਨ ਅਤੇ ਵਰਕਸਪੇਸ ਨਾਲ ਬੱਝੇ ਹਨ। ਕੁੱਲ ਗਿਣਤੀ ਜਾਂ ਅੰਕੀ ਸਫ਼ਾ ਵਾਪਸ ਨਹੀਂ ਆਉਂਦਾ।

ਮੌਜੂਦਾ data ਐਰੇ ਅਤੇ params ਮੈਪ ਉਪਲਬਧ ਰਹਿੰਦੇ ਹਨ। pagination.returned ਅਸਲ ਵਾਪਸ ਗਿਣਤੀ ਹੈ; pagination.has_more ਅਗਲਾ ਸਫ਼ਾ ਦੱਸਦਾ ਹੈ। ਪੂਰਾ ਹੋਣ ਉੱਤੇ next_cursor null ਹੈ। ਜਵਾਬ 524288 ਬਾਈਟਾਂ ਤੱਕ ਸੀਮਿਤ ਹੈ, ਇਸ ਲਈ ਸਫ਼ੇ ਵਿੱਚ per_page ਤੋਂ ਘੱਟ ਇਵੈਂਟ ਹੋ ਸਕਦੇ ਹਨ। ਹਰ ਇਵੈਂਟ ਲਈ ਵੱਧ ਤੋਂ ਵੱਧ 128 ਪੈਰਾਮੀਟਰ ਕਤਾਰਾਂ; ਵੱਧ ਹੋਣ ਉੱਤੇ params_truncated true ਹੈ। ਵੱਖਰੇ ਸਤਰ ਪੈਰਾਮੀਟਰਾਂ ਲਈ ਡਾਟਾਬੇਸ ਦੀ 255 ਅੱਖਰ ਹੱਦ ਰਹਿੰਦੀ ਹੈ। ਕੱਟੇ ਪੈਰਾਮੀਟਰ ਇਸ ਐਂਡਪੁਆਇੰਟ ਰਾਹੀਂ ਨਹੀਂ ਮਿਲਦੇ। per_page ਘਟਾਉਣ ਨਾਲ ਪੈਰਾਮੀਟਰ ਹੱਦ ਨਹੀਂ ਵਧਦੀ।

ਅਵੈਧ ਸਫ਼ਾ ਆਕਾਰ, ਬਦਲੇ ਕਰਸਰ ਅਤੇ ਹੋਰ ਸੈਸ਼ਨ/ਵਰਕਸਪੇਸ ਦੇ ਕਰਸਰ 400 ਦਿੰਦੇ ਹਨ। ਬਹੁਤ ਵੱਡਾ ਵੱਖਰਾ ਇਵੈਂਟ ਡਾਟਾ 413 ਦਿੰਦਾ ਹੈ। ਮੌਜੂਦਾ ਪਹੁੰਚ ਜਾਂਚਾਂ ਲੋੜ ਮੁਤਾਬਕ ਹਾਲੇ 401, 403, 404 ਜਾਂ 409 ਦਿੰਦੀਆਂ ਹਨ।

ਹੱਦ ਹਰ API ਕੁੰਜੀ ਲਈ ਹਰ ਮਿੰਟ 60 ਪ੍ਰਮਾਣਿਤ ਬੇਨਤੀਆਂ ਹੈ। ਮੁੱਕਣ ਉੱਤੇ 429, Retry-After: 60 ਨਾਲ। Redis ਜਾਂ ਲਿਮਿਟਰ ਉਪਲਬਧ ਨਾ ਹੋਵੇ ਤਾਂ 503, Retry-After: 5 ਨਾਲ; ਬਿਨਾਂ ਹੱਦ ਕਦੇ ਨਹੀਂ ਮੰਨੀਆਂ ਜਾਂਦੀਆਂ। Retry-After ਮੰਨੋ ਅਤੇ ਬੇਤਰਤੀਬ ਵਧਦੀ ਉਡੀਕ ਜੋੜੋ; ਤੰਗ ਲੂਪ ਵਿੱਚ ਮੁੜ ਕੋਸ਼ਿਸ਼ ਨਾ ਕਰੋ। ਇਵੈਂਟ ਡਾਟਾਬੇਸ ਨਾਕਾਮੀਆਂ ਵੀ 503 ਦਿੰਦੀਆਂ ਹਨ। ਕਰਸਰ ਸਨੈਪਸ਼ਾਟ ਜਮਾਂਦੇ ਨਹੀਂ: ਪੁਰਾਣੀਆਂ ਸਮਾਂ-ਮੋਹਰਾਂ ਨਾਲ ਇੱਕੋ ਸਮੇਂ ਜੋੜਿਆ ਡਾਟਾ ਨਵਾਂ ਸਕੈਨ ਮੰਗ ਸਕਦਾ ਹੈ।

GET /api/v1/sessions/s_example/events?per_page=25
GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR

/api/v1/native ਨੇਟਿਵ SDK ਝਲਕ ਲਈ ਸਿਰਫ਼ Dev ਦਾ ਬੈਕਐਂਡ ਕੰਟਰੋਲ ਰਸਤਾ ਹੈ। ਉਤਪਾਦਨ ਵਿੱਚ ਬੰਦ ਰਹਿੰਦਾ ਹੈ। ਬੈਕਐਂਡ Bearer ਕੁੰਜੀਆਂ ਨੂੰ list/replay ਲਈ ਪੜ੍ਹਨ ਦਾਇਰਾ ਅਤੇ register/grant/delete/disable ਲਈ ਲਿਖਣ ਦਾਇਰਾ ਚਾਹੀਦਾ ਹੈ। ਵਾਧੂ ਨੇਟਿਵ-ਝਲਕ ਉਪਲਬਧਤਾ ਜਾਂਚਾਂ ਲਾਗੂ ਹਨ। ਮੋਬਾਈਲ ਐਪ ਵਿੱਚ ਪੱਕੀਆਂ ਵਰਕਸਪੇਸ API ਕੁੰਜੀਆਂ ਕਦੇ ਨਾ ਜੋੜੋ।

ਅਸੀਂ ਕਿਵੇਂ ਮਦਦ ਕਰ ਸਕਦੇ ਹਾਂ?