Skip to main content
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

MethodPathDescription
GET/public/ideacloudsList IdeaClouds
GET/public/ideaclouds/{id}Get IdeaCloud details
GET/public/ideaclouds/{id}/questionsGet questions and clusters

​
List IdeaClouds

GET /public/ideaclouds
Returns a paginated list of IdeaClouds for your site.

​
Query parameters

NameTypeDefaultDescription
limitinteger25Number of results to return (1-100)
cursorstring—Base64-encoded cursor from a previous response
statusstring—Filter by status (e.g. researching, complete, failed)
keywordstring—Case-insensitive partial match on keyword

​
Example

curl "https://api.app.hrizn.io/v1/public/ideaclouds?limit=10&status=complete" \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK

{
  "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

CodeDescription
200Success
401Missing or invalid API key
403API key does not have ideaclouds:read scope
500Internal server error

​
Get IdeaCloud details

GET /public/ideaclouds/{id}
Returns full details for a single IdeaCloud.

​
Path parameters

NameTypeRequiredDescription
idstring (UUID)YesIdeaCloud ID

​
Example

curl https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK

{
  "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

CodeDescription
200Success
400IdeaCloud ID is required
401Missing or invalid API key
403API key does not have ideaclouds:read scope
404IdeaCloud not found or belongs to a different site
500Internal 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

NameTypeRequiredDescription
idstring (UUID)YesIdeaCloud ID

​
Example

curl https://api.app.hrizn.io/v1/public/ideaclouds/a1b2c3d4-e5f6-7890-abcd-ef1234567890/questions \
  -H "X-API-Key: hzk_your_key_here"

​
Response — 200 OK (research complete)

{
  "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)

{
  "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

CodeDescription
200Success (check status field for readiness)
400IdeaCloud ID is required
401Missing or invalid API key
403API key does not have ideaclouds:read scope
404IdeaCloud not found or belongs to a different site
500Internal server error

​
Error response — Missing scope

If your API key does not include ideaclouds:read, any request to these endpoints returns: 
{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: ideaclouds:read",
    "details": {
      "required_scopes": ["ideaclouds:read"]
    }
  }
}
Last modified on March 1, 2026