---
canonical_url: "https://docs.composio.dev/toolkits/hypotize"
markdown_url: "https://docs.composio.dev/toolkits/hypotize.md"
product: "platform"
version: null
last_updated: null
---

# Hypotize

Hypotize helps teams capture growth experiment ideas, manage experiment lifecycles, and preserve outcomes and learnings.

- **Category:** product management
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `HYPOTIZE`
- **Version:** 00000000_00

## Tools

### Add Comment

**Slug:** `HYPOTIZE_ADD_COMMENT`

Add a dated comment to an experiment without changing the experiment's updated_at value.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Comment text to add. |
| `experiment_id` | string | Yes | Experiment ID returned by List Experiments or Get Experiment. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse only with identical comment content. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Idea

**Slug:** `HYPOTIZE_CREATE_IDEA`

Create one experiment idea in a project's backlog. Supply an idempotency key to retry safely without creating a duplicate.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | Tags to attach to the idea; each tag must contain 1-100 characters. |
| `title` | string | Yes | Short title for the experiment idea. |
| `funnel` | string ("Awareness" | "Acquisition" | "Activation" | "Revenue" | "Retention" | "Referral") | Yes | Funnel stage this idea targets. |
| `due_date` | string | No | Planned experiment due timestamp in ISO 8601 format. |
| `variants` | array | No | Experiment variants. Each variant requires a stable key and human-readable name. |
| `framework` | string ("ICE" | "PIE" | "RICE" | "CUSTOM") | No | Prioritization framework to use; omit to use the project's active framework. |
| `hypothesis` | string | No | Hypothesis the experiment will test. |
| `project_id` | string | Yes | Project ID returned by List Projects; the API-key user must be an editor or owner. |
| `short_idea` | string | Yes | Concise statement of the experiment idea. |
| `start_date` | string | No | Planned experiment start timestamp in ISO 8601 format. |
| `description` | string | No | Detailed description of the idea. |
| `target_metric` | string | No | Metric the experiment intends to affect. |
| `baseline_value` | string | No | Baseline measurement before the experiment starts. |
| `fail_criterion` | string | No | Criterion that indicates the experiment failed. |
| `success_metric` | string | No | Criterion or measurement that indicates success. |
| `target_segment` | string | No | Audience or segment targeted by the experiment. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse it only with the identical request body. |
| `custom_framework_id` | string | No | Custom framework ID when using a project-defined custom framework. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Experiment

**Slug:** `HYPOTIZE_GET_EXPERIMENT`

Get one experiment with its hypothesis, metrics, score, variants, outcome, and comments.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `experiment_id` | string | Yes | Experiment ID returned by List Experiments or a create/import action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Project

**Slug:** `HYPOTIZE_GET_PROJECT`

Get one project with its active framework, settings, and the API-key user's membership and permissions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID returned by List Projects. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Import Experiments

**Slug:** `HYPOTIZE_IMPORT_EXPERIMENTS`

Atomically import 1-50 existing experiments at any lifecycle stage; one invalid item rolls back the entire batch.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Destination project ID returned by List Projects. |
| `experiments` | array | Yes | Existing experiments to import atomically. Every item requires title, short_idea, and funnel. One invalid item rolls back the entire batch. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse only with the identical batch. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Experiments

**Slug:** `HYPOTIZE_LIST_EXPERIMENTS`

List one page of a project's experiments and ideas, most recently updated first, with optional status, funnel, tag, and update-time filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | Tags to include. Each value is sent as a repeated tags query parameter. |
| `limit` | integer | No | Maximum number of experiments to return in this page (1-100). |
| `cursor` | string | No | Continuation cursor from the previous page's next_cursor; omit for the first page. |
| `funnel` | array | No | Funnel stages to include. Each value is sent as a repeated funnel query parameter. |
| `statuses` | array | No | Experiment statuses to include. Each value is sent as a repeated statuses query parameter. |
| `project_id` | string | Yes | Project ID returned by List Projects. |
| `updated_after` | string | No | Return experiments updated after this timestamp. For polling, use the previous poll time and deduplicate by id plus updated_at. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Learnings

**Slug:** `HYPOTIZE_LIST_LEARNINGS`

List one page of a project's experiment outcomes and learnings, most recently updated first, with optional result, status, and end-time filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of learnings to return in this page (1-100). |
| `cursor` | string | No | Continuation cursor from the previous page's next_cursor; omit for the first page. |
| `results` | array | No | Outcome classifications to include. Each value is sent as a repeated results query parameter. |
| `statuses` | array | No | Experiment statuses to include. Defaults to the provider's final learning statuses; each value is sent as a repeated statuses query parameter. |
| `project_id` | string | Yes | Project ID returned by List Projects. |
| `ended_after` | string | No | Include only experiments ending after this timestamp. This excludes records without an end date and should not be used for polling because a later-recorded outcome can retain an earlier end date. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Projects

**Slug:** `HYPOTIZE_LIST_PROJECTS`

List projects accessible to the API-key user, including each project role and permission flags, one cursor page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of projects to return in this page (1-100). |
| `cursor` | string | No | Continuation cursor from the previous page's next_cursor; omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Record Outcome

**Slug:** `HYPOTIZE_RECORD_OUTCOME`

Record an experiment's measured result and learning, then irreversibly close it in a final status. Uses optimistic concurrency; obtain expected_updated_at from a fresh Get Experiment call.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `result` | string ("Win" | "Lose" | "Neutral") | Yes | Outcome classification. |
| `ended_at` | string | No | Timestamp when the experiment ended. |
| `next_steps` | string | No | Recommended follow-up actions. |
| `final_status` | string ("Winning" | "Failed" | "Inconclusive" | "Learned") | No | Final lifecycle status to assign while closing the experiment. |
| `actual_result` | string | Yes | Measured result and what actually happened. |
| `experiment_id` | string | Yes | Experiment ID returned by List Experiments or Get Experiment. |
| `evidence_links` | array | No | Links to evidence supporting the outcome. |
| `winner_variant` | string | No | Winning variant key, or null when no variant won. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse only with the identical outcome. |
| `learning_summary` | string | Yes | Learning derived from the experiment. |
| `expected_updated_at` | string | Yes | Current experiment updated_at from a fresh read. If Hypotize reports a stale experiment, re-read it before deciding whether to retry. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transition Experiment

**Slug:** `HYPOTIZE_TRANSITION_EXPERIMENT`

Move an experiment to a specified lifecycle status only if expected_updated_at still matches the current record.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to_status` | string ("Approved" | "Ready" | "Running" | "Analyzing" | "Winning" | "Failed" | "Inconclusive" | "Learned" | "Archived") | Yes | Lifecycle status to move the experiment to. |
| `experiment_id` | string | Yes | Experiment ID returned by List Experiments or Get Experiment. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse only with the identical transition. |
| `expected_updated_at` | string | Yes | Current experiment updated_at from a fresh read. If Hypotize returns STALE_EXPERIMENT, re-read before deciding whether to retry. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Experiment

**Slug:** `HYPOTIZE_UPDATE_EXPERIMENT`

Update one or more experiment fields only if expected_updated_at still matches the current record. Omitted fields remain unchanged, while explicit null values clear documented nullable fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | Complete replacement tag list; each tag must contain 1-100 characters. Send an empty list to remove all tags. |
| `title` | string | No | New experiment title. |
| `funnel` | string ("Awareness" | "Acquisition" | "Activation" | "Revenue" | "Retention" | "Referral") | No | New funnel stage. |
| `due_date` | string | No | New due timestamp in ISO 8601 format, or null to clear it. |
| `ended_at` | string | No | New end timestamp in ISO 8601 format, or null to clear it. |
| `variants` | array | No | Complete replacement variant list. Each variant requires a stable key and human-readable name. |
| `hypothesis` | string | No | New hypothesis, or null to clear it. |
| `next_steps` | string | No | Follow-up steps, or null to clear them. |
| `short_idea` | string | No | New concise experiment idea. |
| `start_date` | string | No | New start timestamp in ISO 8601 format, or null to clear it. |
| `description` | string | No | New detailed description, or null to clear it. |
| `actual_result` | string | No | Measured result details, or null to clear them. |
| `experiment_id` | string | Yes | Experiment ID returned by List Experiments or Get Experiment. |
| `target_metric` | string | No | New target metric, or null to clear it. |
| `baseline_value` | string | No | New baseline value, or null to clear it. |
| `evidence_links` | array | No | Complete replacement list of supporting evidence links; each link must contain 1-2048 characters. Send an empty list to remove all links. |
| `fail_criterion` | string | No | New failure criterion, or null to clear it. |
| `success_metric` | string | No | New success criterion, or null to clear it. |
| `target_segment` | string | No | New target segment, or null to clear it. |
| `winner_variant` | string | No | Winning variant key, or null to clear it. |
| `idempotency_key` | string | No | Recommended unique key for safe retries, retained by Hypotize for 24 hours. Reuse it only with the identical update. |
| `learning_summary` | string | No | Learning summary, or null to clear it. |
| `expected_updated_at` | string | Yes | Current experiment updated_at from a fresh read. If Hypotize returns STALE_EXPERIMENT, re-read before deciding whether to retry. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
