ideaclouds:read

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

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

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();

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()

$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`

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

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

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();

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()

$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`

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

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

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();

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()

$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)

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

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:

{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: ideaclouds:read",
    "details": {
      "required_scopes": ["ideaclouds:read"]
    }
  }
}

Getting Started

Concepts

Guides

Scopes

Endpoints

List IdeaClouds

Query parameters

Example

Response — `200 OK`

Status codes

Get IdeaCloud details

Path parameters

Example

Response — `200 OK`

Status codes

Get questions and clusters

Path parameters

Example

Response — `200 OK` (research complete)

Response — `200 OK` (research in progress)

Status codes

Error response — Missing scope

​Endpoints

​List IdeaClouds

​Query parameters

​Example

​Response — 200 OK

​Status codes

​Get IdeaCloud details

​Path parameters

​Example

​Response — 200 OK

​Status codes

​Get questions and clusters

​Path parameters

​Example

​Response — 200 OK (research complete)

​Response — 200 OK (research in progress)

​Status codes

​Error response — Missing scope

Endpoints

List IdeaClouds

Query parameters

Example

Response — `200 OK`

Status codes

Get IdeaCloud details

Path parameters

Example

Response — `200 OK`

Status codes

Get questions and clusters

Path parameters

Example

Response — `200 OK` (research complete)

Response — `200 OK` (research in progress)

Status codes

Error response — Missing scope