pub struct CreateRunRequest {
pub concurrency_key: Option<String>,
pub concurrency_limits: Vec<ConcurrencyLimit>,
pub labels: Option<HashMap<String, String>>,
pub max_cost_usd: Option<f64>,
pub max_retries: Option<i32>,
pub payload: Option<Map<String, Value>>,
pub priority: Option<i32>,
pub scheduled_at: Option<DateTime<Utc>>,
pub worker_tags: Vec<String>,
pub workflow: String,
}Expand description
Request to trigger a workflow.
§Examples
use ironflow_api::entities::CreateRunRequest;
use serde_json::json;
let req = CreateRunRequest {
workflow: "deploy".to_string(),
payload: Some(json!({"env": "prod"})),
labels: None,
scheduled_at: None,
max_retries: Some(2),
max_cost_usd: None,
concurrency_key: Some("issue:12".to_string()),
priority: None,
concurrency_limits: Vec::new(),
worker_tags: vec!["gpu".to_string()],
};
assert_eq!(req.workflow, "deploy");JSON schema
{
"description": "Request to trigger a workflow.\n\n# Examples\n\n```\nuse ironflow_api::entities::CreateRunRequest;\nuse serde_json::json;\n\nlet req = CreateRunRequest {\n workflow: \"deploy\".to_string(),\n payload: Some(json!({\"env\": \"prod\"})),\n labels: None,\n scheduled_at: None,\n max_retries: Some(2),\n max_cost_usd: None,\n concurrency_key: Some(\"issue:12\".to_string()),\n priority: None,\n concurrency_limits: Vec::new(),\n worker_tags: vec![\"gpu\".to_string()],\n};\nassert_eq!(req.workflow, \"deploy\");\n```",
"type": "object",
"required": [
"workflow"
],
"properties": {
"concurrency_key": {
"description": "Optional exclusivity key, at most 255 bytes.\n\nWhile a non-terminal run (pending, running, sleeping, retrying,\nawaiting approval) holds the same key, the request is refused with\n`409 CONCURRENCY_CONFLICT` naming that run. The key is released when\nthe run completes, fails, ends with a warning or is cancelled.",
"type": [
"string",
"null"
]
},
"concurrency_limits": {
"description": "Concurrency groups the run belongs to, each with its own limit.\n\nThe run is always created, but a worker only starts it once, for every\ngroup, fewer root runs of that group than its `limit` are running.\nUntil then it stays pending, and later runs of other groups go ahead.\nEach group is non-empty, at most 255 bytes and listed once; each limit\nis at least 1. Empty means no limit.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ConcurrencyLimit"
}
},
"labels": {
"description": "Optional key-value labels for categorization and filtering.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"max_cost_usd": {
"description": "Optional cumulative cost cap for this run, in USD.\n\nOverrides the workflow default and the server default. `None` falls back\nto those. Must be zero or positive.",
"type": [
"number",
"null"
],
"format": "double"
},
"max_retries": {
"description": "How many times the run may be replayed automatically after a transient\nfailure. Defaults to `0`, meaning no automatic retry.\n\nEach retry waits an exponential backoff (30 s, 2 min, 8 min, capped at\n15 min) before the run is replayed from the start. Failures that cannot\nsucceed on replay -- an unknown workflow, an invalid payload, an\nexhausted agent budget, a rejected approval, a manual cancellation --\nconsume no attempt.",
"type": [
"integer",
"null"
],
"format": "int32",
"minimum": 0.0
},
"payload": {
"description": "Optional input payload for the workflow.",
"type": [
"object",
"null"
],
"additionalProperties": {}
},
"priority": {
"description": "Optional queue priority, from -100 to 100.\n\nWorkers pick the pending run with the highest priority first, then the\noldest among equal priorities. `None` falls back to the workflow\ndefault, itself `0` unless the handler declares one. A running run is\nnever preempted, and a low priority run is not aged: a steady flow of\nhigher priority runs can delay it indefinitely.",
"type": [
"integer",
"null"
],
"format": "int32"
},
"scheduled_at": {
"description": "Optional deferred execution time. `None` means run immediately.",
"type": [
"string",
"null"
],
"format": "date-time"
},
"worker_tags": {
"description": "Tags a worker must carry to take this run, added to the ones the\nworkflow requires.\n\nThe run stays pending until a worker carrying all of them asks for\nwork. Each tag is 1 to 64 bytes of ASCII letters, digits and\n`- _ . : / =`; at most 32 tags. Empty means only the workflow's own\nrequirements apply.",
"type": "array",
"items": {
"type": "string"
}
},
"workflow": {
"description": "The workflow name to trigger.",
"type": "string"
}
}
}
```ignore
</details>Fields§
§concurrency_key: Option<String>Optional exclusivity key, at most 255 bytes.
While a non-terminal run (pending, running, sleeping, retrying,
awaiting approval) holds the same key, the request is refused with
409 CONCURRENCY_CONFLICT naming that run. The key is released when
the run completes, fails, ends with a warning or is cancelled.
concurrency_limits: Vec<ConcurrencyLimit>Concurrency groups the run belongs to, each with its own limit.
The run is always created, but a worker only starts it once, for every
group, fewer root runs of that group than its limit are running.
Until then it stays pending, and later runs of other groups go ahead.
Each group is non-empty, at most 255 bytes and listed once; each limit
is at least 1. Empty means no limit.
labels: Option<HashMap<String, String>>Optional key-value labels for categorization and filtering.
max_cost_usd: Option<f64>Optional cumulative cost cap for this run, in USD.
Overrides the workflow default and the server default. None falls back
to those. Must be zero or positive.
max_retries: Option<i32>How many times the run may be replayed automatically after a transient
failure. Defaults to 0, meaning no automatic retry.
Each retry waits an exponential backoff (30 s, 2 min, 8 min, capped at 15 min) before the run is replayed from the start. Failures that cannot succeed on replay – an unknown workflow, an invalid payload, an exhausted agent budget, a rejected approval, a manual cancellation – consume no attempt.
payload: Option<Map<String, Value>>Optional input payload for the workflow.
priority: Option<i32>Optional queue priority, from -100 to 100.
Workers pick the pending run with the highest priority first, then the
oldest among equal priorities. None falls back to the workflow
default, itself 0 unless the handler declares one. A running run is
never preempted, and a low priority run is not aged: a steady flow of
higher priority runs can delay it indefinitely.
scheduled_at: Option<DateTime<Utc>>Optional deferred execution time. None means run immediately.
Tags a worker must carry to take this run, added to the ones the workflow requires.
The run stays pending until a worker carrying all of them asks for
work. Each tag is 1 to 64 bytes of ASCII letters, digits and
- _ . : / =; at most 32 tags. Empty means only the workflow’s own
requirements apply.
workflow: StringThe workflow name to trigger.