xapi-to 0.1.17 → 0.1.19

package/skills/xapi/guides/douyin.md

@@ -0,0 +1,297 @@
+# Douyin (抖音) Guide
+
+Complete guide for Douyin (抖音) operations via xAPI — user profiles, videos, comments, hot search, hashtags, music, and video statistics.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `douyin` service. Exact action IDs, HTTP methods, parameters, and response fields can change. Run `search` and `get` before calling; the current schema wins. Examples below reflect one known GET-based version and keep `"method":"GET"` in the input for compatibility.
+
+## Contents
+
+- [User data](#user-data)
+- [Video data](#video-data)
+- [Video mixes](#video-mix-合集)
+- [Hot search](#hot-search-热搜)
+- [Hashtags](#hashtags)
+- [Music](#music)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination-patterns)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## User Data
+
+### Get user profile
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_handler__user__profile \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>"}}'
+```
+
+Requires `sec_user_id`. Returns user info at `data.data.user`.
+
+### Get user's videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__post__videos \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","count":10}}'
+```
+
+Requires `sec_user_id`. Paginate with `max_cursor`. Optional: `sort_type`.
+
+### Get user's liked videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__like__videos \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","counts":10}}'
+```
+
+Requires `sec_user_id`. Paginate with `max_cursor`. Note: the parameter is `counts` (with 's'), not `count`.
+
+### Get user fans list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__fans__list \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>","count":20}}'
+```
+
+Paginate with `max_time`.
+
+### Get user series list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__user__series__list \
+  --input '{"method":"GET","params":{"sec_user_id":"<sec_user_id>"}}'
+```
+
+## Video Data
+
+### Get video by ID
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__one__video \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>"}}'
+```
+
+Also available: V2 (`fetch__one__video__v2`) and V3 (`fetch__one__video__v3`, no copyright restrictions).
+
+### Get video by share URL
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__one__video__by__share__url \
+  --input '{"method":"GET","params":{"share_url":"https://v.douyin.com/xxxxx/"}}'
+```
+
+### Batch get videos
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__multi__video \
+  --input '{"method":"GET","params":{"aweme_ids":"id1,id2,id3"}}'
+```
+
+Also available: V2 (`fetch__multi__video__v2`).
+
+### Get video statistics
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__statistics \
+  --input '{"method":"GET","params":{"aweme_ids":"<video_id>"}}'
+```
+
+Returns like count, download count, play count, share count. Supports comma-separated IDs for batch queries.
+
+### Get high quality play URL
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__high__quality__play__url \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>"}}'
+```
+
+Returns the highest quality video play URL.
+
+### Get video comments
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__comments \
+  --input '{"method":"GET","params":{"aweme_id":"<video_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+### Get comment replies
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__comment__replies \
+  --input '{"method":"GET","params":{"item_id":"<video_id>","comment_id":"<comment_id>","count":20,"cursor":0}}'
+```
+
+## Video Mix (合集)
+
+### Get video mix detail
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__mix__detail \
+  --input '{"method":"GET","params":{"mix_id":"<mix_id>"}}'
+```
+
+### Get video mix post list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__video__mix__post__list \
+  --input '{"method":"GET","params":{"mix_id":"<mix_id>","count":20,"cursor":0}}'
+```
+
+Paginate with `cursor`.
+
+### Get series detail
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__series__detail \
+  --input '{"method":"GET","params":{"series_id":"<series_id>"}}'
+```
+
+### Get series video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__series__video__list \
+  --input '{"method":"GET","params":{"series_id":"<series_id>"}}'
+```
+
+## Hot Search (热搜)
+
+### Get Douyin hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+Returns ~50 trending topics at `data.data.data.word_list[]`. Most entries have fields: `word` (topic title), `hot_value`, `view_count`, `event_time`, `position`. Pinned/top entries may only have `word`, `hot_value`, `view_count` without `event_time` or `position`.
+
+Optional: `board_type`, `board_sub_type` for different ranking categories.
+
+### Get brand hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__brand__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+### Get live hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__live__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+## Hashtags
+
+### Get hashtag details
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hashtag__detail \
+  --input '{"method":"GET","params":{"ch_id":123456}}'
+```
+
+Note: `ch_id` is an **integer** for Douyin.
+
+### Get hashtag video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__hashtag__video__list \
+  --input '{"method":"GET","params":{"ch_id":"<hashtag_id>","count":20,"cursor":0}}'
+```
+
+Optional: `sort_type` — `0` = comprehensive, `1` = most likes, `2` = latest first.
+
+## Music
+
+### Get music details
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__detail \
+  --input '{"method":"GET","params":{"music_id":"<music_id>"}}'
+```
+
+### Get music video list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__video__list \
+  --input '{"method":"GET","params":{"music_id":"<music_id>"}}'
+```
+
+### Get music hot search list
+
+```bash
+npx xapi-to call douyin.api_v1_douyin_app_v3_fetch__music__hot__search__list \
+  --input '{"method":"GET","params":{}}'
+```
+
+## Common Workflows
+
+### Track Douyin trending
+
+1. Hot search: `douyin...fetch__hot__search__list` → top 50 trending topics
+2. Brand hot search: `douyin...fetch__brand__hot__search__list` → brand trending
+3. Get video details for a trending topic
+
+### Research a Douyin creator
+
+1. Get profile: `douyin...handler__user__profile` with `sec_user_id` → user info
+2. Get videos: `douyin...fetch__user__post__videos` → browse recent posts
+3. Get stats: `douyin...fetch__video__statistics` → batch check engagement metrics
+
+### Analyze a Douyin video
+
+1. Get video: `douyin...fetch__one__video` with `aweme_id` → full video data
+2. Get stats: `douyin...fetch__video__statistics` → play count, likes, downloads, shares
+3. Read comments: `douyin...fetch__video__comments` → top comments
+4. Get replies: `douyin...fetch__video__comment__replies` → comment threads
+
+### Browse a video series
+
+1. Get series: `douyin...fetch__series__detail` or `douyin...fetch__video__mix__detail`
+2. List videos: `douyin...fetch__series__video__list` or `douyin...fetch__video__mix__post__list`
+
+## Pagination Patterns
+
+| Pattern | Endpoints | How to use |
+|---------|-----------|------------|
+| `max_cursor` | user videos, liked videos | Pass `max_cursor` from previous response |
+| `cursor` | comments, hashtag videos, mix post list | Pass `cursor` from previous response |
+| `max_time` | fans list | Pass `max_time` from previous response |
+
+## API Reference
+
+| API (prefix: `douyin.api_v1_douyin_app_v3_`) | Description | Key Params |
+|---|---|---|
+| `handler__user__profile` | Get user profile | `sec_user_id` |
+| `fetch__user__post__videos` | User's videos | `sec_user_id`, `count`, `max_cursor` |
+| `fetch__user__like__videos` | User's liked videos | `sec_user_id`, `counts`, `max_cursor` |
+| `fetch__user__fans__list` | User's fans | `sec_user_id`, `count`, `max_time` |
+| `fetch__user__series__list` | User's series | `sec_user_id` |
+| `fetch__one__video` | Single video | `aweme_id` |
+| `fetch__one__video__v2` | Single video V2 | `aweme_id` |
+| `fetch__one__video__v3` | Single video V3 (no copyright restrictions) | `aweme_id` |
+| `fetch__one__video__by__share__url` | Video by share URL | `share_url` |
+| `fetch__multi__video` | Batch get videos | `aweme_ids` |
+| `fetch__video__statistics` | Video stats (batch) | `aweme_ids` |
+| `fetch__video__high__quality__play__url` | High quality play URL | `aweme_id` |
+| `fetch__video__comments` | Video comments | `aweme_id`, `count`, `cursor` |
+| `fetch__video__comment__replies` | Comment replies | `item_id`, `comment_id`, `count`, `cursor` |
+| `fetch__video__mix__detail` | Video mix detail | `mix_id` |
+| `fetch__video__mix__post__list` | Video mix posts | `mix_id`, `count`, `cursor` |
+| `fetch__series__detail` | Series detail | `series_id` |
+| `fetch__series__video__list` | Series videos | `series_id` |
+| `fetch__hot__search__list` | Hot search list | `board_type`, `board_sub_type` |
+| `fetch__brand__hot__search__list` | Brand hot search | — |
+| `fetch__live__hot__search__list` | Live hot search | — |
+| `fetch__hashtag__detail` | Hashtag details | `ch_id` (integer) |
+| `fetch__hashtag__video__list` | Hashtag videos | `ch_id`, `count`, `cursor`, `sort_type` |
+| `fetch__music__detail` | Music details | `music_id` |
+| `fetch__music__video__list` | Music videos | `music_id` |
+| `fetch__music__hot__search__list` | Music hot search | — |
+
+## Error Handling
+
+- **Missing sec_user_id** → Douyin requires `sec_user_id` for most user-related endpoints; obtain it through other channels
+- **Empty results** → Check that `aweme_id`, `ch_id`, `mix_id`, or `music_id` is valid
+- **Pagination exhausted** → When `has_more` is `0` or `false`, no more pages available

package/skills/xapi/guides/google_search.md

@@ -0,0 +1,194 @@
+# Google Search Guide
+
+Complete guide for web search operations via xAPI — general search, realtime search, news, images, videos, scholar, maps, places, and shopping.
+
+All search endpoints are capability-type actions under the `web.search` namespace. Parameters are passed directly (no `"method"` or `"params"` wrapper needed).
+
+## Contents
+
+- [Common parameters](#common-parameters)
+- [Web search](#web-search)
+- [News, image, video, and scholar search](#news-search)
+- [Maps and places](#maps-search)
+- [Shopping search](#shopping-search)
+- [Common workflows](#common-workflows)
+- [Localization tips](#localization-tips)
+- [API reference](#api-reference)
+
+## Common Parameters
+
+All search capabilities accept `q`, `gl`, `hl`, and `page`. Most also accept `autocorrect`; `web.search.realtime` does not expose it and deliberately disables autocorrection. Run `get` before relying on optional parameters.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` | string | **(required)** | Search query |
+| `gl` | string | `"us"` | Country code (e.g. `us`, `cn`, `jp`, `de`) |
+| `hl` | string | `"en"` | Language code (e.g. `en`, `zh`, `ja`, `de`) |
+| `page` | number | `1` | Page number for pagination |
+| `autocorrect` | boolean | `true` | Supported by every search capability except `web.search.realtime` |
+
+## Web Search
+
+### General web search
+
+```bash
+npx xapi-to call web.search --input '{"q":"OpenAI GPT-5","num":10}'
+```
+
+Additional parameters:
+- `num` — number of results to return (default 10)
+- `location` — location name for localized results
+
+Returns `data.organic[]` with `title`, `link`, `snippet`, and `position`. The declared response also includes optional `data.knowledgeGraph` and `data.relatedSearches[]`.
+
+### Realtime web search
+
+```bash
+npx xapi-to call web.search.realtime --input '{"q":"breaking news","timeRange":"day","num":10}'
+```
+
+For finding the latest content with time-based filtering.
+
+Additional parameters:
+- `timeRange` — time filter: `"hour"`, `"day"` (default), `"week"`, `"month"`, `"year"`
+- `num` — number of results (default 10)
+- `location` — location for localized results
+
+Returns `data.organic[]` with fields: `title`, `link`, `snippet`, `position`, `date`.
+
+## News Search
+
+```bash
+npx xapi-to call web.search.news --input '{"q":"AI regulation"}'
+```
+
+Search Google News for articles.
+
+Additional parameters:
+- `tbs` — date range filter: `"qdr:h"` (past hour), `"qdr:d"` (past 24h), `"qdr:w"` (past week), `"qdr:m"` (past month), `"qdr:y"` (past year)
+
+Returns `data.news[]` with fields: `title`, `link`, `snippet`, `date`, `source`, `imageUrl`.
+
+## Image Search
+
+```bash
+npx xapi-to call web.search.image --input '{"q":"aurora borealis"}'
+```
+
+Search Google Images.
+
+Additional parameters:
+- `tbs` — date range filter (same values as news)
+
+Returns `data.images[]` with fields: `title`, `imageUrl`, `imageWidth`, `imageHeight`, `thumbnailUrl`, `source`, `domain`, `link`.
+
+## Video Search
+
+```bash
+npx xapi-to call web.search.video --input '{"q":"machine learning tutorial"}'
+```
+
+Search Google Videos (primarily YouTube results).
+
+Additional parameters:
+- `tbs` — date range filter (same values as news)
+
+Returns `data.videos[]` with declared fields `title`, `link`, `snippet`, `channel`, `date`, and `duration`.
+
+## Scholar Search
+
+```bash
+npx xapi-to call web.search.scholar --input '{"q":"transformer architecture attention"}'
+```
+
+Search Google Scholar for academic papers and citations.
+
+Returns `data.organic[]` with declared fields `title`, `link`, `snippet`, `publicationInfo`, `citedBy`, and `year`.
+
+## Maps Search
+
+```bash
+npx xapi-to call web.search.maps --input '{"q":"coffee shop near Times Square"}'
+```
+
+Search Google Maps for locations and businesses.
+
+Additional parameters:
+- `ll` — latitude/longitude coordinates to center the search (e.g. `"@40.7455096,-74.0083012,14z"`)
+
+Returns `data.places[]` with declared fields `title`, `address`, `latitude`, `longitude`, `rating`, `ratingCount`, and `category`.
+
+## Places Search
+
+```bash
+npx xapi-to call web.search.places --input '{"q":"best ramen in Tokyo","gl":"jp"}'
+```
+
+Search for businesses and places with richer contact details. Use this capability when phone number or website is important.
+
+Additional parameters:
+- `location` — location name to scope the search (e.g. `"San Francisco, California, United States"`)
+- `ll` — latitude/longitude coordinates (e.g. `"@37.7749295,-122.4194155,14z"`)
+
+Returns `data.places[]` with declared fields `title`, `address`, `latitude`, `longitude`, `rating`, `ratingCount`, `category`, `phoneNumber`, and `website`.
+
+## Shopping Search
+
+```bash
+npx xapi-to call web.search.shopping --input '{"q":"mechanical keyboard"}'
+```
+
+Search Google Shopping for products and prices.
+
+Additional parameters:
+- `tbs` — date range filter
+- `location` — location affecting prices and availability
+
+Returns `data.shopping[]` with declared fields `title`, `source`, `link`, `price`, `rating`, `ratingCount`, and `imageUrl`.
+
+The upstream provider can return additional fields that are not part of the capability's declared schema. Treat them as opportunistic: inspect the current `get` output and actual response before depending on them.
+
+## Common Workflows
+
+### Research a topic
+
+1. Web search: `web.search` → get authoritative sources
+2. News search: `web.search.news` → get latest developments
+3. Scholar search: `web.search.scholar` → find academic papers
+
+### Monitor breaking news
+
+1. Realtime search: `web.search.realtime` with `timeRange: "hour"` → latest content
+2. News search: `web.search.news` with `tbs: "qdr:h"` → latest news articles
+
+### Find a local business
+
+1. Maps search: `web.search.maps` with `ll` coordinates → find nearby listings and coordinates
+2. Places search: `web.search.places` → add phone numbers and websites when the upstream provides them
+
+### Product research
+
+1. Shopping search: `web.search.shopping` → compare prices and ratings
+2. Web search: `web.search` with `"<product> review"` → find reviews
+
+## Localization Tips
+
+- Set `gl` (country) and `hl` (language) together for best results:
+  - Chinese results: `"gl":"cn","hl":"zh"`
+  - Japanese results: `"gl":"jp","hl":"ja"`
+  - German results: `"gl":"de","hl":"de"`
+- Use `location` (for `web.search`, `web.search.realtime`, `web.search.places`, `web.search.shopping`) for city-level localization
+
+## API Reference
+
+| Capability | Description | Result Field | Key Result Fields |
+|------------|-------------|--------------|-------------------|
+| `web.search` | General web search | `organic[]` | `title`, `link`, `snippet`, `position` |
+| `web.search.realtime` | Realtime web search | `organic[]` | `title`, `link`, `snippet`, `date` |
+| `web.search.news` | News articles | `news[]` | `title`, `link`, `source`, `date` |
+| `web.search.image` | Image search | `images[]` | `title`, `imageUrl`, `imageWidth`, `imageHeight` |
+| `web.search.video` | Video search | `videos[]` | `title`, `link`, `channel`, `duration` |
+| `web.search.scholar` | Academic papers | `organic[]` | `title`, `link`, `citedBy`, `year` |
+| `web.search.maps` | Map locations | `places[]` | `title`, `address`, `latitude`, `longitude`, `category` |
+| `web.search.places` | Detailed business listings | `places[]` | `title`, `address`, `category`, `phoneNumber`, `website` |
+| `web.search.shopping` | Product search | `shopping[]` | `title`, `price`, `source`, `rating`, `imageUrl` |

package/skills/xapi/guides/linkedin.md

@@ -0,0 +1,198 @@
+# LinkedIn Guide
+
+Complete guide for LinkedIn operations via xAPI — person profiles with career history, company pages, posts and comments, and job search.
+
+> **Dynamic catalog:** These are database-registered third-party APIs under the `linkedin` service. Exact action IDs, HTTP methods, parameters, response fields, charging, and retry behavior can change. Run `search` and `get` before calling; the current schema and live response win. Examples below reflect the `linkedin_web v2` version and keep `"method":"GET"` in the input for compatibility.
+
+## Contents
+
+- [Key concept: everything is addressed by URL](#key-concept-everything-is-addressed-by-url)
+- [Person data](#person-data)
+- [Company data](#company-data)
+- [Posts and comments](#posts-and-comments)
+- [Jobs](#jobs)
+- [Common workflows](#common-workflows)
+- [Pagination](#pagination)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+
+## Key Concept: everything is addressed by URL
+
+Every `linkedin_web v2` endpoint except job search is addressed by an ordinary public LinkedIn page URL passed as `url`. There is no separate ID-resolution step: paste the URL you would open in a browser. The one extra parameter is `urn` on [post comments](#get-comments-on-a-post), and it is derived from the post URL.
+
+| Resource | URL shape |
+|----------|-----------|
+| Person | `https://www.linkedin.com/in/<vanity>/` |
+| Company | `https://www.linkedin.com/company/<slug>/` |
+| Post | `https://www.linkedin.com/feed/update/urn:li:activity:<id>/` or `https://www.linkedin.com/posts/<slug>-activity-<id>-<hash>` |
+| Job | `https://www.linkedin.com/jobs/view/<job_id>` |
+
+Discover the current endpoint set before relying on any list here:
+
+```bash
+npx xapi-to search "linkedin" --source api
+npx xapi-to get linkedin.api_v1_linkedin_web__v2_get__user__profile
+```
+
+## Person Data
+
+### Get a profile
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
+```
+
+One call returns the whole profile — no follow-up requests for individual sections. `data.data` contains:
+
+- Identity: `name`, `first_name`, `last_name`, `id` (vanity), `linkedin_id`, `linkedin_num_id`, `url`, `avatar`, `banner_image`, `influencer`
+- Headline & summary: `position`, `about`, `unformatted_about`, `bio_links`
+- Location: `city`, `location`, `country_code`
+- Career: `experience[]`, `current_company`, `current_company_name`, `current_company_company_id`
+- Education: `education[]`, `educations_details`
+- Recognition: `honors_and_awards[]`
+- Social proof: `followers`, `connections`, `activity[]`, `posts[]`
+- Discovery: `people_also_viewed[]`, `similar_profiles[]`
+
+There are no separate `get__user__experience` / `educations` / `skills` / `honors` / `publications` endpoints in v2 — that was the older `username` → `urn` two-step API. If you were using those IDs, they now return `Action not found`.
+
+### Get a person's posts
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__posts \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/","page":1}}'
+```
+
+Returns `data.data.data[]` plus `data.data.paging`. Each item carries `urn`, `post_url`, `text`, `time`/`posted`, `poster`, `images[]`, and a reaction breakdown (`num_likes`, `num_comments`, `num_reposts`, `num_reactions`, `num_empathy`, `num_praises`, …).
+
+Keep `urn` from here — it is the numeric activity ID that [post comments](#get-comments-on-a-post) additionally requires.
+
+## Company Data
+
+### Get a company page
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__company__profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/company/anthropicresearch/"}}'
+```
+
+Returns `data.data` with `name`, `company_id`, `about`, `description`, `slogan`, `website`, `industries`, `company_size`, `organization_type`, `followers`, `employees_in_linkedin`, `employees[]`, `locations[]`, `logo`, `image`, `similar[]`, `affiliated[]`, `alumni` / `alumni_information`, `updates[]`.
+
+### Get a company's posts
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__company__posts \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/company/anthropicresearch/","page":1}}'
+```
+
+Same envelope as person posts: `data.data.data[]` + `data.data.paging`.
+
+## Posts and Comments
+
+### Get post detail
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__post__detail \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/feed/update/urn:li:activity:7490874650621612032/"}}'
+```
+
+Returns the full post: `post_text`, `post_text_html`, `title`, `headline`, `date_posted`, `hashtags[]`, `embedded_links[]`, `images[]`, `videos[]`, `num_likes`, `num_comments`, `top_visible_comments[]`, `repost`, `tagged_people[]`, `tagged_companies[]`, `external_link_data`, plus author context (`user_name`, `user_title`, `user_followers`, `author_profile_pic`).
+
+### Get comments on a post
+
+**This endpoint requires two parameters, not one** — `url` *and* `urn`, the bare numeric activity ID. Both are marked required in the schema, and `urn` is pattern-validated as `^[0-9]+$`.
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__post__comments \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/feed/update/urn:li:activity:7490874650621612032/","urn":"7490874650621612032","page":1}}'
+```
+
+Extract `urn` from the post URL — the digits after `activity:` (feed form) or after `-activity-` (posts form). Passing the prefixed `urn:li:activity:7490874650621612032` form is rejected by the pattern check before the call is billed.
+
+Returns `data.data.data[]` with `text`, `commenter`, `created_at`, `created_datetime`, `permalink`, `pinned`, `replies`, `thread_urn`, plus `data.data.total` and `data.data.pagination_token`.
+
+## Jobs
+
+### Search jobs
+
+The one endpoint that is not URL-addressed:
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_search__jobs \
+  --input '{"method":"GET","params":{"keywords":"machine learning engineer","location":"United States","page":1}}'
+```
+
+`keywords` is required; `location` and `page` are optional. Returns `data.data.data[]` (`job_title`, `job_url`, `job_urn`, `company`, `company_linkedin_url`, `company_logo`, `location`, `remote`, `salary`, `posted_time`) plus `data.data.total`.
+
+### Get job detail
+
+```bash
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__job__detail \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/jobs/view/4442605025"}}'
+```
+
+Returns `data.data.data` with the full JD (`job_description`), `job_title`, `job_type`, `experience_level`, `job_functions[]`, `skills[]`, `salary_details`, `salary_display`, `benefits[]`, `remote_allow`, `applies`, `views`, `posted`, `closed`/`expired`, `hiring_team[]`, and company context (`company_name`, `company_id`, `company_description`, `employee_count`, `industries[]`, `hq_*` address fields).
+
+This is the most expensive LinkedIn endpoint — search first, then fetch detail only for the postings you actually care about.
+
+## Common Workflows
+
+### Profile → recent activity
+
+```bash
+# 1. Whole profile in one call
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__profile \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/"}}'
+
+# 2. Their posts (take `urn` from each item for step 3)
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__user__posts \
+  --input '{"method":"GET","params":{"url":"https://www.linkedin.com/in/williamhgates/","page":1}}'
+
+# 3. Comments on one post — url AND numeric urn
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__post__comments \
+  --input '{"method":"GET","params":{"url":"<post_url>","urn":"<urn>","page":1}}'
+```
+
+### Job hunt
+
+```bash
+# 1. Search (cheap, paginated)
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_search__jobs \
+  --input '{"method":"GET","params":{"keywords":"rust engineer","location":"Berlin","page":1}}'
+
+# 2. Detail only for shortlisted job_url values
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__job__detail \
+  --input '{"method":"GET","params":{"url":"<job_url>"}}'
+
+# 3. Company context
+npx xapi-to call linkedin.api_v1_linkedin_web__v2_get__company__profile \
+  --input '{"method":"GET","params":{"url":"<company_linkedin_url>"}}'
+```
+
+## Pagination
+
+`get__user__posts`, `get__company__posts`, `get__post__comments`, and `search__jobs` take a 1-based `page` integer. Posts responses carry `data.data.paging`; comments carry `total` and `pagination_token`; job search carries `total`. Increment `page` until a response comes back exhausted — note that past the last page the upstream returns `code: 200` with `data: null` (not an empty array), so test for falsy rather than for `length === 0`. The other four endpoints return a complete resource and take no pagination parameter.
+
+## API Reference
+
+| Action ID (`linkedin.api_v1_linkedin_web__v2_…`) | Purpose | Required params | Optional |
+|---|---|---|---|
+| `get__user__profile` | Full person profile + experience/education/honors | `url` | — |
+| `get__user__posts` | A person's posts | `url` | `page` |
+| `get__company__profile` | Company page | `url` | — |
+| `get__company__posts` | A company's posts | `url` | `page` |
+| `get__post__detail` | Single post, full text and media | `url` | — |
+| `get__post__comments` | Comments on a post | `url` **and** `urn` (digits only) | `page` |
+| `search__jobs` | Job search | `keywords` | `location`, `page` |
+| `get__job__detail` | Full job posting | `url` | — |
+
+Detail-style endpoints (`get__*__profile`, `get__post__detail`) are the cheapest; list-style endpoints (posts, comments, job search) cost more per call, and `get__job__detail` is the most expensive. Run `npx xapi-to get <action-id>` for the current `meta.pricing` rather than assuming these ratios hold.
+
+## Error Handling
+
+- **`Action not found: linkedin.api_v1_linkedin_web_…`** — you used a pre-v2 action ID. The `username` → `urn` two-step endpoints (`get__user__experience`, `get__user__educations`, `get__user__skills`, `get__user__contact`, `search__people`, `get__company__jobs`, …) are gone; everything is now `…_linkedin_web__v2_…` and URL-addressed. Re-discover with `npx xapi-to search "linkedin" --source api`.
+- **`Input validation failed … must have required property 'url'`** — the gateway rejected the call before it reached LinkedIn. Check the `params` object, not `pathParams`.
+- **`must have required property 'urn'`** — `get__post__comments` needs the numeric `urn` alongside `url`. See [Get comments on a post](#get-comments-on-a-post).
+- **`must match pattern "^[0-9]+$"` on `/params/urn`** — you passed the prefixed `urn:li:activity:<id>` form. Send the digits only.
+- **`API Token lacks required permissions`** (upstream `403`) — the account's upstream provider token has no LinkedIn scope. This is an account entitlement, not a parameter problem; enable it in the provider dashboard.
+- **Empty `data[]` on a valid URL** — either the page is private/deleted, or you paginated past the end. LinkedIn also rate-limits aggressively; retry with backoff rather than in a tight loop.