Agents

Sample requests for Agent endpoints.

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

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.

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 to find the agent ID.
2. Use Get an Agent to inspect the input schema.
3. Use Run an Agent with an inputs object keyed by the schema’s property names.
4. Use Get an Agent Run to check whether the run succeeded or failed.

1. List Agents

First, identify the agent you want to run:

GET /v1/agents?statuses=published&limit=100 HTTP/1.1
X-API-Key: your_api_key

{
  "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.

GET /v1/agents/your_agent_id?version=published HTTP/1.1
X-API-Key: your_api_key

{
  "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."
    }
  }
}

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.

3. Run an Agent

Now start a run using that input key:

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>"
  }
}

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

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.

4. Get an Agent Run

Finally, fetch the run result:

GET /v1/agents/your_agent_id/runs/your_run_id HTTP/1.1
X-API-Key: your_api_key

{
  "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>"
  }
}