> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt > Use this file to discover all available pages before exploring further. # ideaclouds:read > List and retrieve IdeaClouds, research questions, and question clusters ideaclouds:read The `ideaclouds:read` scope grants read-only access to IdeaClouds and their associated research data. Use this to list IdeaClouds, view their status, retrieve individual details, and access the questions and clusters produced during research. ## Endpoints | Method | Path | Description | | ------ | ----------------------------------- | -------------------------- | | `GET` | `/public/ideaclouds` | List IdeaClouds | | `GET` | `/public/ideaclouds/{id}` | Get IdeaCloud details | | `GET` | `/public/ideaclouds/{id}/questions` | Get questions and clusters | *** ## List IdeaClouds ``` GET /public/ideaclouds ``` Returns a paginated list of IdeaClouds for your site. ### Query parameters | Name | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------------------------------- | | `limit` | integer | `25` | Number of results to return (1-100) | | `cursor` | string | — | Base64-encoded cursor from a previous response | | `status` | string | — | Filter by status (e.g. `researching`, `complete`, `failed`) | | `keyword` | string | — | Case-insensitive partial match on keyword | ### Example ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.app.hrizn.io/v1/public/ideaclouds?limit=10&status=complete" \ -H "X-API-Key: hzk_your_key_here" ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} const res = await fetch( "https://api.app.hrizn.io/v1/public/ideaclouds?limit=10&status=complete", { headers: { "X-API-Key": "hzk_your_key_here" } } ); const data = await res.json(); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import requests response = requests.get( "https://api.app.hrizn.io/v1/public/ideaclouds", headers={"X-API-Key": "hzk_your_key_here"}, params={"limit": 10, "status": "complete"}, ) data = response.json() ``` ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}} $url = "https://api.app.hrizn.io/v1/public/ideaclouds?" . http_build_query([ "limit" => 10, "status" => "complete", ]); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"], CURLOPT_RETURNTRANSFER => true, ]); $data = json_decode(curl_exec($ch)); ``` ### Response — `200 OK` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "data": [ { "id": "a1186354-df73-44bc-8c02-22f07991822f", "keyword": "2026 Toyota Corolla Cross Hybrid fuel economy", "title": "2026 Corolla Cross Hybrid: Fuel Economy", "synopsis": "Comprehensive analysis of the 2026 Toyota Corolla Cross Hybrid's fuel economy, range, and related factors.", "status": "complete", "category": { "id": "8496413e-6a0b-42d5-a027-3a9586576701", "name": "2025 Toyota Camry" }, "created_at": "2026-02-28T02:46:00.785807+00:00", "updated_at": "2026-02-28T02:46:00.785807+00:00" }, { "id": "894b3b99-a59a-41bf-97fc-ac0f5eeb2490", "keyword": "2026 Toyota GR86 Performance Review", "title": "2026 Toyota GR86: Performance Deep Dive", "synopsis": "This analysis covers the 2026 Toyota GR86's performance, specs, pricing, and compares it to competitors.", "status": "complete", "category": null, "created_at": "2026-02-28T02:11:14.681399+00:00", "updated_at": "2026-02-28T02:11:14.681399+00:00" } ], "pagination": { "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAy...", "total_count": 66 } } ``` ### Status codes | Code | Description | | ----- | --------------------------------------------- | | `200` | Success | | `401` | Missing or invalid API key | | `403` | API key does not have `ideaclouds:read` scope | | `500` | Internal server error | *** ## Get IdeaCloud details ``` GET /public/ideaclouds/{id} ``` Returns full details for a single IdeaCloud. ### Path parameters | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------ | | `id` | string (UUID) | Yes | IdeaCloud ID | ### Example ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "X-API-Key: hzk_your_key_here" ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} const res = await fetch( "https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890", { headers: { "X-API-Key": "hzk_your_key_here" } } ); const data = await res.json(); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import requests response = requests.get( "https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890", headers={"X-API-Key": "hzk_your_key_here"}, ) data = response.json() ``` ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}} $ch = curl_init("https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890"); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"], CURLOPT_RETURNTRANSFER => true, ]); $data = json_decode(curl_exec($ch)); ``` ### Response — `200 OK` ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "data": { "id": "a1186354-df73-44bc-8c02-22f07991822f", "keyword": "2026 Toyota Corolla Cross Hybrid fuel economy", "title": "2026 Corolla Cross Hybrid: Fuel Economy", "synopsis": "Comprehensive analysis of the 2026 Toyota Corolla Cross Hybrid's fuel economy, range, and related factors.", "tags": ["2026 Corolla Cross Hybrid", "fuel economy", "hybrid MPG", "Toyota hybrid", "compact SUV", "driving range"], "status": "complete", "category": null, "recommended_questions": [ { "id": "q-1772246824308-0", "question": "What is the fuel economy of the 2026 Toyota Corolla Cross Hybrid?" }, { "id": "q-1772246824308-1", "question": "How does real-world fuel economy compare to the EPA estimate?" }, { "id": "q-1772246824309-5", "question": "What is the maximum driving range for the 2026 Corolla Cross Hybrid?" } ], "created_at": "2026-02-28T02:46:00.785807+00:00", "updated_at": "2026-02-28T02:46:00.785807+00:00" } } ``` ### Status codes | Code | Description | | ----- | -------------------------------------------------- | | `200` | Success | | `400` | IdeaCloud ID is required | | `401` | Missing or invalid API key | | `403` | API key does not have `ideaclouds:read` scope | | `404` | IdeaCloud not found or belongs to a different site | | `500` | Internal server error | *** ## Get questions and clusters ``` GET /public/ideaclouds/{id}/questions ``` Returns the research questions and clusters for an IdeaCloud. If research is still in progress, the questions array will be empty and a status message is included. ### Path parameters | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------ | | `id` | string (UUID) | Yes | IdeaCloud ID | ### Example ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890/questions \ -H "X-API-Key: hzk_your_key_here" ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} const res = await fetch( "https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890/questions", { headers: { "X-API-Key": "hzk_your_key_here" } } ); const data = await res.json(); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} import requests response = requests.get( "https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890/questions", headers={"X-API-Key": "hzk_your_key_here"}, ) data = response.json() ``` ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}} $ch = curl_init("https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890/questions"); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"], CURLOPT_RETURNTRANSFER => true, ]); $data = json_decode(curl_exec($ch)); ``` ### Response — `200 OK` (research complete) ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "data": { "id": "a1186354-df73-44bc-8c02-22f07991822f", "status": "complete", "questions": [ { "id": "q-1772246824308-0", "question": "What is the fuel economy of the 2026 Toyota Corolla Cross Hybrid?", "cluster_id": "cluster-0", "source_url": "https://www.edmunds.com/toyota/corolla-cross-hybrid/2026/", "source_title": null, "is_recommended": true }, { "id": "q-1772246824308-1", "question": "How does real-world fuel economy compare to the EPA estimate?", "cluster_id": "cluster-0", "source_url": "https://www.edmunds.com/toyota/corolla-cross-hybrid/2026/review/", "source_title": null, "is_recommended": true }, { "id": "q-1772246824309-30", "question": "How does the Corolla Cross Hybrid compare to the RAV4 Hybrid?", "cluster_id": "cluster-3", "source_url": "https://www.caranddriver.com/comparisons/", "source_title": null, "is_recommended": true } ], "clusters": [ { "id": "cluster-0", "label": "Fuel Economy and Efficiency", "question_count": 10 }, { "id": "cluster-3", "label": "Competitor Comparisons", "question_count": 5 } ], "recommended_question_ids": [ "q-1772246824308-0", "q-1772246824308-1", "q-1772246824309-30" ] } } ``` ### Response — `200 OK` (research in progress) ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "data": { "id": "a1186354-df73-44bc-8c02-22f07991822f", "status": "researching", "questions": [], "clusters": [], "message": "IdeaCloud research is still in progress" } } ``` Poll this endpoint to check when research completes. Once `status` is `"complete"`, the `questions` and `clusters` arrays will be populated. You can also subscribe to the `ideacloud.completed` webhook event instead of polling. ### Status codes | Code | Description | | ----- | -------------------------------------------------- | | `200` | Success (check `status` field for readiness) | | `400` | IdeaCloud ID is required | | `401` | Missing or invalid API key | | `403` | API key does not have `ideaclouds:read` scope | | `404` | IdeaCloud not found or belongs to a different site | | `500` | Internal server error | *** ## Error response — Missing scope If your API key does not include `ideaclouds:read`, any request to these endpoints returns: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "code": "forbidden", "message": "This API key requires one of the following scopes: ideaclouds:read", "details": { "required_scopes": ["ideaclouds:read"] } } } ```