Graine AI
API referenceAgents

List agents

List the organisation's agents, newest first by default.

List the organisation's agents, newest first by default.

A row here and the agent read on its own carry the same keys, so you can write one decoder for both. Two fields are necessarily thinner on a row: prompts comes back empty and knowledge_base null, because neither is fetched while listing. Everything else — the greeting, the labels, the seven configuration buckets — is the same object.

Two other behaviours worth knowing:

  • A page can come back with fewer rows than you asked for — this is normal. Creating an agent also creates an internal browser-calling companion that shares its prompt. Those are removed from the results after the page is fetched, so page_size=20 commonly returns about 10 agents, and page_size=1 can return none at all. A short page does NOT mean the end of the list.
  • Use has_more, never total, to decide whether to keep going. has_more is authoritative. total is an estimate: it counts what is upstream and subtracts the companions removed from the page being returned, so it shifts with page_size and is not a number to divide. Iterate until has_more is false and collect what arrives.

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
/v2/agents?status=ACTIVE&category=support&search=support&sort_by=created_at&sort_order=desc&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

Query Parameters

statusStatus

DRAFT | ACTIVE | INACTIVE | ARCHIVED. ARCHIVED agents are excluded unless this filter names them explicitly.

categoryCategory

Filter by the agent's category.

searchSearch

Substring match on the agent's name.

sort_bySort By

created_at | updated_at | name | status

Default: "created_at"

sort_orderSort Order

asc | desc

Default: "desc"

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 agents, newest first by default. Each row carries the same keys as GET /v2/agents/{agent_id}.

data
Required
Data

This page of agents, newest first by default.

pagination
Required
Pagination

Where this page sits in the result set.

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

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 instead of an API key.

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 organization. GET /v2/scopes reports what a 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.

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 — the per-organization request rate or concurrent-call limit was reached. 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 — a service this endpoint depends on 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 — a service this endpoint depends on did not answer 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?status=ACTIVE&category=support&search=support&sort_by=created_at&sort_order=desc&organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of agents, newest first by default. Each row carries the same keys as GET /v2/agents/{agent_id}.

{
  "data": [
    {
      "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29",
      "display_name": "Priya Plumber Activation Agent",
      "summary": "Activates plumbers who signed up but never scanned a code.",
      "greeting_message": "Hello! Am I speaking with {callee_name}?",
      "status": "DRAFT",
      "category": "other",
      "version": 1,
      "timestamps": {
        "created_at": "2026-08-20T13:06:01.724Z",
        "updated_at": "2026-08-20T13:27:49.073Z"
      },
      "labels": [
        "activation",
        "hindi"
      ],
      "prompts": {
        "conversation": {
          "system": "You are Priya, a warm caller from ..."
        },
        "summarization": {
          "system": "You are Priya, a warm caller from ..."
        },
        "extraction": {
          "system": "You are Priya, a warm caller from ..."
        }
      },
      "variables": {
        "custom": [
          "callee_name",
          "mobile_number"
        ],
        "placeholders": [
          "callee_name",
          "mobile_number"
        ],
        "_original_format": "string"
      },
      "analytics": {
        "custom": [
          {
            "name": "Lead qualification",
            "prompt": "Read the transcript and fill in each field.",
            "required_keys": [
              "intent",
              "callback_time"
            ]
          }
        ]
      },
      "integrations": {
        "webhook": {
          "url": "https://example.com/hooks/graine"
        },
        "webcall": {
          "enabled": true
        }
      },
      "knowledge_base": "product-handbook",
      "conversation_config": {
        "finale_message": "Thank you for your time.",
        "presence_probe_message": "Are you still on the call?",
        "probe_interval_seconds": 7,
        "probe_window_seconds": 30,
        "probe_min_words": 7,
        "block_unlisted_callers": false
      },
      "configuration": {
        "runtime": {
          "call_transport": {
            "provider": "default",
            "audio_format": "wav"
          },
          "speech_recognition": {
            "provider": "deepgram",
            "model": "nova-3",
            "language": "hi",
            "stream": true,
            "endpointing": 190,
            "encoding": "linear16",
            "sampling_rate": 16000,
            "task": "transcribe",
            "keywords": "haan,ji,bolo,pearl,sparsh"
          },
          "voice_synthesis": {
            "provider": "cartesia",
            "voice_id": "148a02f1-d396-4615-8552-52483eaf9d9a",
            "voice_name": "Laxmi",
            "speed": 1,
            "speaking_rate": 1,
            "audio_format": "wav",
            "buffer_size": 500,
            "stream": true,
            "caching": true,
            "model": "sonic-3.5"
          },
          "language_model": {
            "provider": "azure",
            "model": "azure/gpt-4o-mini-2",
            "agent_type": "simple_llm_agent",
            "config": {
              "max_tokens": 300,
              "temperature": 0.25
            },
            "knowledge_base_config": {
              "enabled": true,
              "collections": [
                "internal_organization-live-EXAMPLE__product-handbook"
              ],
              "similarity_top_k": 5,
              "max_results": 3,
              "reranker_enabled": true
            }
          }
        },
        "session_policy": {
          "session_ttl": 300,
          "close_after_reply": true,
          "finale_interruptible": false,
          "completion_probe": true,
          "probe_interval_seconds": 7,
          "auto_retry_plan": true,
          "trusted_callers": [
            "+917971442184"
          ],
          "silence_close_after": 12,
          "block_unlisted_callers": false,
          "entry_quota": -1,
          "probe_window_seconds": 30,
          "probe_min_words": 7,
          "probe_start_delay_seconds": 2.5
        },
        "stream_policy": {
          "bargein_word_threshold": 3,
          "force_chunking": true,
          "rapid_path_mode": true,
          "transcript_fidelity_mode": false,
          "emit_step_ms": 200,
          "bargein_backoff_ms": 0,
          "interrupt_on_speech_start": true
        },
        "engagement_policy": {
          "noise_guard_level": 2,
          "scene_bed_gain": -11,
          "listener_cues_enabled": false,
          "presence_probe_enabled": true,
          "keypad_signal_gate": false,
          "presence_probe_after_seconds": 6,
          "listener_cue_gap_seconds": 5,
          "locale_probe_turns": 2,
          "scene_bed_enabled": true,
          "scene_profile_id": "https://ambientsoundgraineai.s3.ap-south-1.amazonaws.com/office-ambience.mp3",
          "cadence_padding": false,
          "listener_cue_start_delay_seconds": 5,
          "presence_probe_message": "Are you still on the line?"
        },
        "message_policy": {
          "completion_probe_prompt": "You are judging whether a conversation is finished. It is finished when the customer's question has been answered and neither side has anything left to add.",
          "finale_message": "Thank you for your time."
        },
        "compliance_policy": {
          "pii_guard_enabled": false
        },
        "post_processing": [
          {
            "type": "summary",
            "enabled": true
          }
        ],
        "external_functions": [
          {
            "name": "check_order_status",
            "description": "Look up an order by its id.",
            "parameters": {
              "type": "object",
              "properties": {
                "order_id": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "settings": {
        "agent_memory": false
      },
      "follow_up_config": {
        "follow_up_agent_id": "b2e9c7a4-5d31-4f68-9c02-7a1b3e5d9f84",
        "follow_up_prompt": "Read the finished call. If the customer asked to be called back, greet them by name and confirm the slot they asked for.",
        "follow_up_extra_logic": {
          "skip_if_ordered": true
        }
      },
      "multilingual": {
        "enabled": true,
        "active_language": "hi",
        "languages": {
          "hi": {
            "agent_name": "Priya"
          },
          "en": {
            "agent_name": "Priya"
          }
        }
      },
      "calling_guard": {
        "enabled": true,
        "timezone": "Asia/Kolkata",
        "start": "09:00",
        "end": "21:00",
        "days": [
          0,
          1,
          2,
          3,
          4
        ]
      },
      "dropped_languages": [
        "ta"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

Fetch one agent GET

Next

Clone an agent POST