Overview
The Graph Workflow API enables you to create and execute complex multi-agent workflows using a directed graph structure. Agents serve as nodes in the graph, and edges define the flow of data and execution between agents. This allows for sophisticated parallel processing, sequential pipelines, and complex multi-layer workflows. Endpoint:POST /v1/graph-workflow/completions
Base URL: https://api.swarms.world (production) or your custom deployment URL
Architecture
You define the shape yourself: agents are nodes,edges are the arrows. Branches run in
parallel and rejoin wherever two edges meet the same node.
Authentication
All requests require an API key passed in thex-api-key header:
Input Parameters
GraphWorkflowInput Schema
AgentSpec Schema
EdgeSpec Schema
Edge Format:
- Each edge is an object:
{"source": "Agent1", "target": "Agent2", "metadata": {...}}.metadatais optional. - A JSON array edge such as
["Agent1", "Agent2"]returns 422. - An edge object without both
sourceandtarget(e.g.{"from": ..., "to": ...}), or one naming an agent that isn’t inagents, returns 400.
Output Parameters
GraphWorkflowOutput Schema
Usage Schema
Cost Calculation
Graph Workflow bills $0.01 per agent plus each agent’s provider-reported tokens, priced at that agent’s own model plus a 15% service fee. No night-time discount applies. For detailed pricing information, see the Pricing page. Only nodes that answered are billed. A node that fails pays no agent fee, and its[ERROR] text isn’t counted as output tokens. The other nodes still run, and the request returns 200 with the failed node’s [ERROR] string in outputs, so check outputs for values that start with [ERROR]. If every node fails, the request returns an error and nothing is charged (see below).
Error Responses
If no node produces output, the request fails with the provider’s error instead of a
200, and nothing is charged. The detail ends with “Nothing was charged.”:
Examples
Example 1: Basic Sequential Workflow
This example demonstrates a simple two-agent sequential workflow where one agent performs research and another analyzes the results.Example 2: Parallel Workflow with Multiple Entry Points
This example demonstrates a workflow with multiple parallel entry points that converge into a single analysis agent.Example 3: Complex Multi-Layer Workflow
This example demonstrates a sophisticated three-layer workflow with data collection, analysis, validation, and synthesis stages.Example 4: Workflow with Edge Metadata
This example demonstrates how to use custom metadata on edges to provide additional context and configuration.Example 5: Async Workflow with Vision Support
This example demonstrates an asynchronous workflow request with image input for vision-enabled agents.Best Practices
- Agent Naming: Use descriptive, unique names for agents as they serve as node identifiers in the graph.
-
Entry and End Points: Always specify
entry_pointsandend_pointsto ensure predictable workflow execution. -
Edge Definitions: Ensure all edges reference valid agent names. The source and target must match
agent_namevalues. -
Timeout Configuration: Set appropriate timeouts based on workflow complexity:
- Simple workflows: 300 seconds (5 minutes)
- Medium workflows: 600 seconds (10 minutes)
- Complex workflows: 900+ seconds (15+ minutes)
-
Error Handling: Always check response status codes and handle errors appropriately. Use try-except blocks for network errors. A
200can still contain a failed node, so checkoutputsfor values that start with[ERROR]. -
Token Management: Monitor token usage through the
usagefield in responses to optimize costs and stay within limits. -
Model Selection: Choose appropriate models based on task requirements:
- For vision tasks: Use vision-capable models like
gpt-4.1 - For complex reasoning: Use models like
claude-sonnet-5 - For cost efficiency: Use
gpt-4.1-minifor simpler tasks
- For vision tasks: Use vision-capable models like
-
Workflow Compilation: Keep
auto_compileenabled (default) for optimal performance, unless you need to debug workflow structure. - Parallel Execution: Design workflows with multiple entry points to leverage parallel execution capabilities.
- Metadata Usage: Use edge metadata to provide additional context or configuration that can be used by custom workflow logic.
Rate Limits
Rate limits are enforced per API key and subscription tier:- Free Tier: 100 requests per minute, 350 requests per hour, 1,200 requests per day
- Premium Tier: 2,000 requests per minute, 10,000 requests per hour, 100,000 requests per day
X-RateLimit-Limit-Minute: Requests allowed per minuteX-RateLimit-Remaining-Minute: Requests remaining in the current minuteX-RateLimit-Limit-Day: Requests allowed per dayX-RateLimit-Remaining-Day: Requests remaining todayX-RateLimit-Reset: Unix timestamp when the minute window resetsX-RateLimit-Tier: Your current tier (freeorpremium)
Support
For additional support, examples, and updates:- Check the main documentation: Swarms API Documentation
- Review example code in the
examples/multi_agent/graph_workflow/directory - Contact support through your Swarms dashboard