> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Sample requests for Agent endpoints.

This guide provides practical examples of common Agent API requests. All examples require authentication via API key.

<Note>
  Replace `your_api_key`, `your_agent_id`, and `your_run_id` with your actual values. Use the list endpoint first to discover the agents available to your organization.
</Note>

## Starter Template walkthrough

Suppose you created an agent using **Profound's Starter Template**. This agent has one required text input labeled **Any Text (This is an example input)**.

This is the typical flow:

1. Use [**List Agents**](/api-reference/agents/list-agents) to find the agent ID.
2. Use [**Get an Agent**](/api-reference/agents/get-an-agent) to inspect the input schema.
3. Use [**Run an Agent**](/api-reference/agents/run-an-agent) with an `inputs` object keyed by the schema's property names.
4. Use [**Get an Agent Run**](/api-reference/agents/get-an-agent-run) to check whether the run succeeded or failed.

### 1. List Agents

First, identify the agent you want to run:

```http theme={null}
GET /v1/agents?statuses=published&limit=100 HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "data": [
    {
      "id": "your_agent_id",
      "organization_id": "your_organization_id",
      "name": "Starter Template",
      "status": "published",
      "created_at": "2026-04-24T19:03:15.459951Z",
      "description": "This template is a simple starter agent that helps you get familiar with how the tool works. Try it out, customize it, and then build your own!"
    }
  ]
}
```

### 2. Get an Agent

Next, retrieve the agent and inspect its schema. This response gives you the agent's input schema and output schema as JSON Schema. You use `schema.input` to determine which fields are required and which variable IDs to send in the `inputs` object when you run the agent. You can also use `schema.output` to understand the shape of the result you'll get back from the run.

```http theme={null}
GET /v1/agents/your_agent_id?version=published HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "id": "your_agent_id",
  "organization_id": "your_organization_id",
  "name": "Starter Template",
  "status": "published",
  "created_at": "2026-04-24T19:03:15.459951Z",
  "description": "This template is a simple starter agent that helps you get familiar with how the tool works. Try it out, customize it, and then build your own!",
  "schema": {
    "input": {
      "type": "object",
      "properties": {
        "your_input_variable_id": {
          "type": "string",
          "title": "Any Text (This is an example input)"
        }
      },
      "additionalProperties": false,
      "description": "Provide inputs as an object keyed by variable ID.",
      "required": ["your_input_variable_id"]
    },
    "output": {
      "type": "object",
      "properties": {
        "your_output_variable_id": {
          "type": "string",
          "title": "Example LLM Output"
        }
      },
      "additionalProperties": false,
      "description": "Agent outputs are returned as an object keyed by variable ID."
    }
  }
}
```

<Tip>
  The `inputs` object must use the schema property key as the field name. In this case, the required input key is `your_input_variable_id`, not the human-readable label.
</Tip>

### 3. Run an Agent

Now start a run using that input key:

```http theme={null}
POST /v1/agents/your_agent_id/runs HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "inputs": {
    "your_input_variable_id": "<your_input_value>"
  }
}
```

```json theme={null}
{
  "id": "your_run_id",
  "agent_id": "your_agent_id",
  "status": "queued",
  "started_at": "2026-04-24T19:08:34.495737Z"
}
```

<Info>
  This endpoint returns `202 Accepted`. A successful submission only means the run was accepted; you still need to fetch the run to see whether it ultimately succeeded or failed.
</Info>

### 4. Get an Agent Run

Finally, fetch the run result:

```http theme={null}
GET /v1/agents/your_agent_id/runs/your_run_id HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "id": "your_run_id",
  "agent_id": "your_agent_id",
  "status": "succeeded",
  "started_at": "2026-04-24T20:53:08.241633Z",
  "finished_at": "2026-04-24T20:53:09.314671Z",
  "outputs": {
    "your_output_variable_id": "<your_output_value>"
  }
}
```