Graine AI
API referenceAgent versions

List an agent's A/B experiments

List every A/B experiment whose control agent is this agent.

List every A/B experiment whose control agent is this agent.

Experiments in which this agent is merely the variant are not listed here — they belong to the control agent's path. total is an honest count of the matching experiments, not a page-size echo, so total_pages and has_more can be trusted.

Filter with ?status= to find the one that is currently live: GET /v2/agents/{agent_id}/versions?status=active.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/agents/{agent_id}/versions
/v2/agents/6c6f4cc3-f56c-479d-8422-7f76694daa29/versions?status=active&page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Path Parameters

agent_id
Required
Agent Id

The CONTROL agent whose experiments are listed.

Query Parameters

statusStatus

Filter by lifecycle state: draft | active | paused | concluded.

organization_idOrganization Id

Must match the organisation the API key belongs to.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of experiments, newest first.

data
Required
Data

This page of experiments, newest first.

pagination
Required
Pagination

Where this page sits in the result set.

400

1000 — malformed or contradictory input: an unknown status token, an empty patch body, an explicit null, or a variant agent that does not exist in this organisation.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such agent, or no such version for that agent, in this organisation. Cross-tenant reads answer 404, never 403, so ids cannot be probed.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — the agent service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — the agent service did not respond in time.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X GET "https://api.graine.ai/v2/agents/6c6f4cc3-f56c-479d-8422-7f76694daa29/versions?status=active&organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of experiments, newest first.

{
  "data": [
    {
      "version_id": "9f1c0f7e-1f2a-4c3b-8a11-2c6a0a5f8d10",
      "main_agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
      "variant_agent_id": "85598652-87ce-4585-93e3-e03a42259796",
      "version_name": "Warmer opening line",
      "description": "Testing a warmer opening line against the current script.",
      "variable_tested": "script",
      "variant_traffic_pct": 50,
      "status": "active",
      "winner": "variant",
      "start_date": "2026-08-20T13:06:01.724Z",
      "end_date": "2026-08-27T09:30:00.000Z",
      "created_by": "dev_1a2b3c4d5e6f7a8b",
      "created_at": "2026-08-20T13:06:01.724Z",
      "updated_at": "2026-08-20T13:27:49.073Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

Get an A/B experiment GET

Next

Create an A/B experiment POST