experiments
Read or change a project's experiments. Pass action "list", "fetch", "query", "import", "remove", or "is_dupe". import stores a concluded test and starts a learning in the background. Do not send processed_results. remove cannot be undone.
Operation ID: experiments
Read or change a project's experiments. Pass action "list", "fetch", "query", "import", "remove", or "is_dupe". import stores a concluded test and starts a learning in the background. Do not send processed_results. remove cannot be undone.
When to use: You need experiments in a project, one experiment by id, a semantic search, a duplicate check, or to store or undo an import.
Returns: list and query and is_dupe: { experiments }. fetch: one experiment. import: { experiment_id, experiment }. remove: { experiment_id, removed_learning_ids }.
| Field | Type | Required | Description |
|---|---|---|---|
action | string | Yes | One of "list", "fetch", "query", "import", "remove", "is_dupe". |
id | uuid | No | Experiment id. Required for fetch and remove. |
project_id | uuid | No | Project id from projects with action "list". Required for list, query, import, and is_dupe. |
query | string | No | Natural-language search text. Required for query. 1–2000 characters. |
limit | integer | No | Page size for list (default 50) or max matches for query (default 10). Max 50. |
cursor | string | No | Opaque cursor from the previous list page's nextCursor. Omit for the first page. |
order_by | string | No | list sort. created_at (default), updated_at, start_date, end_date, or name. |
order | string | No | list direction. desc (default) or asc. |
experiment | object | No | The concluded experiment to store. Required for import. Garasu computes processed_results. |
experiment_spec | object | No | The proposed experiment. Required for is_dupe. The embedding uses name and hypothesis. Jev also reads content when you send it. |
experiment fields:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Display title. Max 200 characters. When omitted, Garasu uses the first 200 characters of the hypothesis. |
hypothesis | string | Yes | What was tested and why. 1–8000 characters. |
start_date | string | Yes | When the test started, as ISO 8601. |
end_date | string | Yes | When the test ended, as ISO 8601. Must be on or after start_date. |
variant_keys | string[] | Yes | Every arm, including the control. At least two unique keys. |
control_variant_key | string | Yes | The control arm. Must be one of variant_keys. |
raw_results | object[] | Yes | One row per metric per variant. At least two. Each row needs metric, variant_key, users, and conversions or mean. |
metadata | object | No | Source details, such as source and source_id. Defaults to {}. |
conclusion | string | No | Outcome label, such as won, lost, or inconclusive. Max 40 characters. |
conclusion_summary | string | No | Short write-up of the outcome. Max 8000 characters. |
winning_variant | string | No | Winning arm, when the source named one. Max 80 characters. |
experiment.raw_results[] fields:
| Field | Type | Required | Description |
|---|---|---|---|
metric | string | Yes | Metric name. Max 120 characters. |
variant_key | string | Yes | Arm this row belongs to. Must be one of variant_keys. |
users | integer | Yes | Sample size. Must be greater than 0. |
conversions | integer | No | Conversion count for a rate metric. Cannot exceed users. |
mean | number | No | Observed mean for a continuous metric. Required when conversions is omitted. |
variance | number | No | Sample variance of the per-user metric. Preferred for mean metrics. |
sum_squares | number | No | Sum of squares of the per-user metric. Used when variance is omitted. |
experiment_spec fields:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display title. Max 200 characters. title is accepted as an alias. |
hypothesis | string | Yes | What the test would change and why. 1–8000 characters. |
content | string | No | Optional fuller spec, such as variants and the primary metric. Max 12000 characters. |
Function schema:
{
"name": "experiments",
"description": "Read or change a project's experiments. Pass action \"list\", \"fetch\", \"query\", \"import\", \"remove\", or \"is_dupe\". import stores a concluded test and starts a learning in the background. Do not send processed_results. remove cannot be undone. You need experiments in a project, one experiment by id, a semantic search, a duplicate check, or to store or undo an import.",
"parameters": {
"type": "object",
"additionalProperties": false,
"properties": {
"action": {
"type": "string",
"description": "One of \"list\", \"fetch\", \"query\", \"import\", \"remove\", \"is_dupe\"."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Experiment id. Required for fetch and remove."
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Project id from projects with action \"list\". Required for list, query, import, and is_dupe."
},
"query": {
"type": "string",
"description": "Natural-language search text. Required for query. 1–2000 characters."
},
"limit": {
"type": "integer",
"description": "Page size for list (default 50) or max matches for query (default 10). Max 50."
},
"cursor": {
"type": "string",
"description": "Opaque cursor from the previous list page's nextCursor. Omit for the first page."
},
"order_by": {
"type": "string",
"description": "list sort. created_at (default), updated_at, start_date, end_date, or name."
},
"order": {
"type": "string",
"description": "list direction. desc (default) or asc."
},
"experiment": {
"type": "object",
"description": "The concluded experiment to store. Required for import. Garasu computes processed_results.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Display title. Max 200 characters. When omitted, Garasu uses the first 200 characters of the hypothesis."
},
"hypothesis": {
"type": "string",
"description": "What was tested and why. 1–8000 characters."
},
"start_date": {
"type": "string",
"description": "When the test started, as ISO 8601."
},
"end_date": {
"type": "string",
"description": "When the test ended, as ISO 8601. Must be on or after start_date."
},
"variant_keys": {
"type": "array",
"description": "Every arm, including the control. At least two unique keys.",
"items": {
"type": "string"
}
},
"control_variant_key": {
"type": "string",
"description": "The control arm. Must be one of variant_keys."
},
"raw_results": {
"type": "array",
"description": "One row per metric per variant. At least two. Each row needs metric, variant_key, users, and conversions or mean.",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"metric": {
"type": "string",
"description": "Metric name. Max 120 characters."
},
"variant_key": {
"type": "string",
"description": "Arm this row belongs to. Must be one of variant_keys."
},
"users": {
"type": "integer",
"description": "Sample size. Must be greater than 0."
},
"conversions": {
"type": "integer",
"description": "Conversion count for a rate metric. Cannot exceed users."
},
"mean": {
"type": "number",
"description": "Observed mean for a continuous metric. Required when conversions is omitted."
},
"variance": {
"type": "number",
"description": "Sample variance of the per-user metric. Preferred for mean metrics."
},
"sum_squares": {
"type": "number",
"description": "Sum of squares of the per-user metric. Used when variance is omitted."
}
},
"required": [
"metric",
"variant_key",
"users"
]
}
},
"metadata": {
"type": "object",
"description": "Source details, such as source and source_id. Defaults to {}.",
"additionalProperties": true,
"properties": {}
},
"conclusion": {
"type": "string",
"description": "Outcome label, such as won, lost, or inconclusive. Max 40 characters."
},
"conclusion_summary": {
"type": "string",
"description": "Short write-up of the outcome. Max 8000 characters."
},
"winning_variant": {
"type": "string",
"description": "Winning arm, when the source named one. Max 80 characters."
}
},
"required": [
"hypothesis",
"start_date",
"end_date",
"variant_keys",
"control_variant_key",
"raw_results"
]
},
"experiment_spec": {
"type": "object",
"description": "The proposed experiment. Required for is_dupe. The embedding uses name and hypothesis. Jev also reads content when you send it.",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Display title. Max 200 characters. title is accepted as an alias."
},
"hypothesis": {
"type": "string",
"description": "What the test would change and why. 1–8000 characters."
},
"content": {
"type": "string",
"description": "Optional fuller spec, such as variants and the primary metric. Max 12000 characters."
}
},
"required": [
"name",
"hypothesis"
]
}
},
"required": [
"action"
]
}
}experiments · list
List a project's experiments. Each row includes processed results, a headline, and related learnings. Pass nextCursor to fetch the next page.
When to use: You need the experiments in a project, or the next page of that list.
Returns: { experiments: [{ id, project_id, name, hypothesis, start_date, end_date, variant_keys, control_variant_key, metadata, headline, processed_results, related_learning_ids, related_learnings, created_at, updated_at, source_url }], nextCursor }
Prompt: List experiments in this Garasu project.
Request:
{
"action": "list",
"project_id": "11111111-1111-4111-8111-111111111111",
"limit": 50,
"order_by": "created_at",
"order": "desc"
}Response:
{
"experiments": [
{
"id": "22222222-2222-4222-8222-222222222222",
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01",
"end_date": "2026-03-28",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
},
"headline": {
"metric": "Checkout completion",
"variant_key": "estimate",
"lift_relative": 7.2993,
"p_value": 0.1389,
"control_n": 24105,
"variant_n": 24105
},
"processed_results": [
{
"metric": "Checkout completion",
"variant_key": "estimate",
"control_variant_key": "control",
"control_n": 24105,
"variant_n": 24105,
"control_mean": 0.034101,
"variant_mean": 0.03659,
"lift_absolute": 0.002489,
"lift_relative": 7.2993,
"p_value": 0.1389,
"z_score": 1.4799,
"post_hoc_power": 32,
"mde80_relative": 13.8182,
"kind": "rate",
"control_variance": 0.032939,
"variant_variance": 0.035251
}
],
"related_learning_ids": [
"44444444-4444-4444-8444-444444444444",
"55555555-5555-4555-8555-555555555555"
],
"related_learnings": [
{
"id": "44444444-4444-4444-8444-444444444444",
"title": "Shipping estimates lift checkout completion",
"summary": "Showing an estimated shipping range on cart raised checkout completion. People dropped off when cost appeared for the first time at payment.",
"strength_of_evidence": 0.72,
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/learnings/44444444-4444-4444-8444-444444444444"
}
],
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/experiments/22222222-2222-4222-8222-222222222222",
"created_at": "2026-03-29T14:12:00.000Z",
"updated_at": "2026-03-29T14:12:00.000Z"
}
],
"nextCursor": null
}experiments · fetch
Get an experiment by id, including raw results.
When to use: You have an experiment id and need the saved experiment, including raw results.
Returns: { id, project_id, name, hypothesis, start_date, end_date, variant_keys, control_variant_key, metadata, headline, processed_results, related_learning_ids, related_learnings, raw_results, created_at, updated_at, source_url }
Prompt: Get the Garasu experiment with this id.
Request:
{
"action": "fetch",
"id": "22222222-2222-4222-8222-222222222222"
}Response:
{
"id": "22222222-2222-4222-8222-222222222222",
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01",
"end_date": "2026-03-28",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
},
"headline": {
"metric": "Checkout completion",
"variant_key": "estimate",
"lift_relative": 7.2993,
"p_value": 0.1389,
"control_n": 24105,
"variant_n": 24105
},
"processed_results": [
{
"metric": "Checkout completion",
"variant_key": "estimate",
"control_variant_key": "control",
"control_n": 24105,
"variant_n": 24105,
"control_mean": 0.034101,
"variant_mean": 0.03659,
"lift_absolute": 0.002489,
"lift_relative": 7.2993,
"p_value": 0.1389,
"z_score": 1.4799,
"post_hoc_power": 32,
"mde80_relative": 13.8182,
"kind": "rate",
"control_variance": 0.032939,
"variant_variance": 0.035251
}
],
"related_learning_ids": [
"44444444-4444-4444-8444-444444444444",
"55555555-5555-4555-8555-555555555555"
],
"related_learnings": [
{
"id": "44444444-4444-4444-8444-444444444444",
"title": "Shipping estimates lift checkout completion",
"summary": "Showing an estimated shipping range on cart raised checkout completion. People dropped off when cost appeared for the first time at payment.",
"strength_of_evidence": 0.72,
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/learnings/44444444-4444-4444-8444-444444444444"
}
],
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/experiments/22222222-2222-4222-8222-222222222222",
"created_at": "2026-03-29T14:12:00.000Z",
"updated_at": "2026-03-29T14:12:00.000Z",
"raw_results": [
{
"metric": "Checkout completion",
"variant_key": "control",
"users": 24105,
"conversions": 822
},
{
"metric": "Checkout completion",
"variant_key": "estimate",
"users": 24105,
"conversions": 882
}
]
}experiments · query
Search a project's experiments by semantic similarity of the title and hypothesis. Returns the closest matches, not a full catalog.
When to use: You need experiments in this project related to a question or hypothesis.
Returns: { experiments: [{ id, project_id, name, hypothesis, similarity, headline, processed_results, related_learnings, source_url }] }
Prompt: Find experiments in this Garasu project about shipping estimates.
Request:
{
"action": "query",
"project_id": "11111111-1111-4111-8111-111111111111",
"query": "shipping estimate",
"limit": 10
}Response:
{
"experiments": [
{
"id": "22222222-2222-4222-8222-222222222222",
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01",
"end_date": "2026-03-28",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
},
"headline": {
"metric": "Checkout completion",
"variant_key": "estimate",
"lift_relative": 7.2993,
"p_value": 0.1389,
"control_n": 24105,
"variant_n": 24105
},
"processed_results": [
{
"metric": "Checkout completion",
"variant_key": "estimate",
"control_variant_key": "control",
"control_n": 24105,
"variant_n": 24105,
"control_mean": 0.034101,
"variant_mean": 0.03659,
"lift_absolute": 0.002489,
"lift_relative": 7.2993,
"p_value": 0.1389,
"z_score": 1.4799,
"post_hoc_power": 32,
"mde80_relative": 13.8182,
"kind": "rate",
"control_variance": 0.032939,
"variant_variance": 0.035251
}
],
"related_learning_ids": [
"44444444-4444-4444-8444-444444444444",
"55555555-5555-4555-8555-555555555555"
],
"related_learnings": [
{
"id": "44444444-4444-4444-8444-444444444444",
"title": "Shipping estimates lift checkout completion",
"summary": "Showing an estimated shipping range on cart raised checkout completion. People dropped off when cost appeared for the first time at payment.",
"strength_of_evidence": 0.72,
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/learnings/44444444-4444-4444-8444-444444444444"
}
],
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/experiments/22222222-2222-4222-8222-222222222222",
"created_at": "2026-03-29T14:12:00.000Z",
"updated_at": "2026-03-29T14:12:00.000Z",
"similarity": 0.84
}
]
}experiments · import
Add a concluded experiment. Embeds the title and hypothesis, stores the experiment, and starts a learning extraction job.
When to use: You have a concluded test with results and want it stored on a project. Skip drafts and tests that are still running.
Returns: { experiment_id, experiment }
Prompt: Import this concluded shipping-estimate experiment into the Garasu project.
Request:
{
"action": "import",
"project_id": "11111111-1111-4111-8111-111111111111",
"experiment": {
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01T00:00:00.000Z",
"end_date": "2026-03-28T00:00:00.000Z",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"raw_results": [
{
"metric": "Checkout completion",
"variant_key": "control",
"users": 24105,
"conversions": 822
},
{
"metric": "Checkout completion",
"variant_key": "estimate",
"users": 24105,
"conversions": 882
}
],
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
}
}
}Response:
{
"experiment_id": "22222222-2222-4222-8222-222222222222",
"experiment": {
"id": "22222222-2222-4222-8222-222222222222",
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01",
"end_date": "2026-03-28",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
},
"headline": {
"metric": "Checkout completion",
"variant_key": "estimate",
"lift_relative": 7.2993,
"p_value": 0.1389,
"control_n": 24105,
"variant_n": 24105
},
"processed_results": [
{
"metric": "Checkout completion",
"variant_key": "estimate",
"control_variant_key": "control",
"control_n": 24105,
"variant_n": 24105,
"control_mean": 0.034101,
"variant_mean": 0.03659,
"lift_absolute": 0.002489,
"lift_relative": 7.2993,
"p_value": 0.1389,
"z_score": 1.4799,
"post_hoc_power": 32,
"mde80_relative": 13.8182,
"kind": "rate",
"control_variance": 0.032939,
"variant_variance": 0.035251
}
],
"related_learning_ids": [],
"related_learnings": [],
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/experiments/22222222-2222-4222-8222-222222222222",
"created_at": "2026-03-29T14:12:00.000Z",
"updated_at": "2026-03-29T14:12:00.000Z",
"raw_results": [
{
"metric": "Checkout completion",
"variant_key": "control",
"users": 24105,
"conversions": 822
},
{
"metric": "Checkout completion",
"variant_key": "estimate",
"users": 24105,
"conversions": 882
}
]
}
}experiments · remove
Undo one import. Deletes that experiment, its joins, and any learning left with no experiments. Cannot be undone.
When to use: An experiments call with action "import" stored the wrong experiment and you need to remove it. Not for clearing a project.
Returns: { experiment_id, removed_learning_ids }
Confirm with the user before calling this. It cannot be undone.
Prompt: Remove the experiment I just imported.
Request:
{
"action": "remove",
"id": "22222222-2222-4222-8222-222222222222"
}Response:
{
"experiment_id": "22222222-2222-4222-8222-222222222222",
"removed_learning_ids": [
"44444444-4444-4444-8444-444444444444"
]
}experiments · is_dupe
Check whether a proposed experiment has already been run in this project. Returns only stored experiments whose Jev score is above 0.9, most similar first.
When to use: You have a new experiment spec and need to know if this project already ran it. An empty list means it has not been run.
Returns: { experiments: [{ id, name, hypothesis, similarity, headline, source_url }] }
Prompt: Has this shipping-estimate experiment already been run in the Garasu project?
Request:
{
"action": "is_dupe",
"project_id": "11111111-1111-4111-8111-111111111111",
"experiment_spec": {
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment."
}
}Response:
{
"experiments": [
{
"id": "22222222-2222-4222-8222-222222222222",
"project_id": "11111111-1111-4111-8111-111111111111",
"name": "Cart shipping estimate",
"hypothesis": "If we show an estimated shipping range on cart, checkout completion will go up because people stop getting surprised by cost at payment.",
"start_date": "2026-03-01",
"end_date": "2026-03-28",
"variant_keys": [
"control",
"estimate"
],
"control_variant_key": "control",
"metadata": {
"source": "posthog",
"source_id": "cart-shipping-estimate"
},
"headline": {
"metric": "Checkout completion",
"variant_key": "estimate",
"lift_relative": 7.2993,
"p_value": 0.1389,
"control_n": 24105,
"variant_n": 24105
},
"processed_results": [
{
"metric": "Checkout completion",
"variant_key": "estimate",
"control_variant_key": "control",
"control_n": 24105,
"variant_n": 24105,
"control_mean": 0.034101,
"variant_mean": 0.03659,
"lift_absolute": 0.002489,
"lift_relative": 7.2993,
"p_value": 0.1389,
"z_score": 1.4799,
"post_hoc_power": 32,
"mde80_relative": 13.8182,
"kind": "rate",
"control_variance": 0.032939,
"variant_variance": 0.035251
}
],
"related_learning_ids": [
"44444444-4444-4444-8444-444444444444",
"55555555-5555-4555-8555-555555555555"
],
"related_learnings": [
{
"id": "44444444-4444-4444-8444-444444444444",
"title": "Shipping estimates lift checkout completion",
"summary": "Showing an estimated shipping range on cart raised checkout completion. People dropped off when cost appeared for the first time at payment.",
"strength_of_evidence": 0.72,
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/learnings/44444444-4444-4444-8444-444444444444"
}
],
"source_url": "https://garasu.co/app/77777777-7777-4777-8777-777777777777/projects/11111111-1111-4111-8111-111111111111/experiments/22222222-2222-4222-8222-222222222222",
"created_at": "2026-03-29T14:12:00.000Z",
"updated_at": "2026-03-29T14:12:00.000Z",
"similarity": 0.94
}
]
}