Workflows

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

The endpoints are named agents, but they list and run Workflows, the node-based automations from the Workflow Builder. Agents built with AI Marketer (Aim) aren’t available through the API yet.

Replace your_api_key, your_agent_id, and your_run_id with your actual values. Use the list endpoint first to discover the Workflows available to your organization.

Starter Template walkthrough

Suppose you created a Workflow using Profound’s Starter Template. This Workflow has one required text input labeled Any Text (This is an example input). This is the typical flow:

Use List Agents to find the Workflow ID.
Use Get an Agent to inspect the input schema.
Use Run an Agent with an inputs object keyed by the schema’s property names.
Use Get an Agent Run to check whether the run succeeded or failed.

1. List Agents

First, identify the Workflow 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 Workflow and inspect its schema. This response gives you the Workflow’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 Workflow. 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>"
  }
}

Get Started

API Reference

Integrations

SDKs

Starter Template walkthrough

1. List Agents

2. Get an Agent

3. Run an Agent

4. Get an Agent Run

​Starter Template walkthrough

​1. List Agents

​2. Get an Agent

​3. Run an Agent

​4. Get an Agent Run

Starter Template walkthrough

1. List Agents

2. Get an Agent

3. Run an Agent

4. Get an Agent Run