Swarm runs

Launch a journey

Answers 202: the run row exists and its fan-out has started. It is not finished — poll GET /projects/{projectId}/journey-runs/{runId} until status leaves running.

SPENDS. A launch fans out into targets × sessionsPerTarget chat sessions, every one of which runs a model on your organization’s account.

Two different 429s can come back and they mean different waits: the per-minute burst brake (retry in seconds) and your plan’s daily launch cap (resets at UTC midnight). Both normally carry Retry-After — honor it when it is there, and back off on your own when it is not, rather than blocking on a header that may not come. A retried Idempotency-Key consumes NO quota.

POST

projects

{projectId}

journeys

{journeyId}

runs

Launch a journey

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "waveId": "<string>",
  "environmentIds": [
    "<string>"
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs"

payload = {
    "waveId": "<string>",
    "environmentIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({waveId: '<string>', environmentIds: ['<string>']})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'waveId' => '<string>',
    'environmentIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs"

	payload := strings.NewReader("{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "journeyId": "<string>",
  "projectId": "<string>",
  "status": "running",
  "deduped": true
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Headers

Idempotency-Key

string

Send one. A launch spends model credits, so a retry of a dropped response must not run the journey twice. Replaying a key returns the ORIGINAL run with deduped: true and starts no second runner.

Omitting the header is read as a request that declined to identify itself, and gets a FRESH run every time.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

journeyId

string

required

Journey ID, as returned by the project's journey list.

Body

application/json

Optional launch options. Omit the body entirely to run the journey as authored.

Optional. A launch with no options is a BODYLESS POST — omit the body entirely rather than sending null, which is rejected.

waveId

string

Opaque id linking the sibling runs of one co-launched batch. Mint it yourself and reuse it across the launches you want grouped.

Maximum string length: 64

environmentIds

string[]

Fan out across THESE environments instead of the journey's authored targets. NON-EMPTY when present: [] is a caller saying "across these" while naming none, and would have silently launched the authored targets instead. Silently running something other than what was asked for is bad anywhere; on an operation that spends it is worse. Omit the field to mean "as authored".

Minimum array length: 1

Response

The run was accepted and started.

string

required

The run id. Poll it, or stop it with cancel.

journeyId

string

required

projectId

string

required

status

enum<string>

required

Always running — the run row exists and its fan-out has started. This is a 202: nothing here says the journey has finished, only that it is under way.

Available options:

running

deduped

boolean

required

True when an Idempotency-Key replayed onto a run that ALREADY existed, so nothing new was started. The response is otherwise identical, which is how a retry of a dropped request tells "I launched it" from "it was already going" without a second read.

⌘I

Launch a journey

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "waveId": "<string>",
  "environmentIds": [
    "<string>"
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs"

payload = {
    "waveId": "<string>",
    "environmentIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({waveId: '<string>', environmentIds: ['<string>']})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'waveId' => '<string>',
    'environmentIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs"

	payload := strings.NewReader("{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/journeys/{journeyId}/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"waveId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "journeyId": "<string>",
  "projectId": "<string>",
  "status": "running",
  "deduped": true
}

API Guides

Endpoints

Launch a journey

Authorizations

Headers

Path Parameters

Body

Response