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}/goal-runs/{runId} until status leaves running.

SPENDS. A launch fans out into targets × iterations 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}

goals

{goalId}

runs

Launch a journey

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

import requests

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

payload = {
    "swarmRunId": "<string>",
    "environmentIds": ["<string>"],
    "expectedSponsored": 1
}
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({swarmRunId: '<string>', environmentIds: ['<string>'], expectedSponsored: 1})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/goals/{goalId}/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}/goals/{goalId}/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([
    'swarmRunId' => '<string>',
    'environmentIds' => [
        '<string>'
    ],
    'expectedSponsored' => 1
  ]),
  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}/goals/{goalId}/runs"

	payload := strings.NewReader("{\n  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\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}/goals/{goalId}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/goals/{goalId}/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  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\n}"

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

{
  "id": "<string>",
  "goalId": "<string>",
  "projectId": "<string>",
  "status": "running",
  "deduped": true,
  "funding": {
    "sponsored": 123,
    "credits": 123,
    "total": 123
  }
}

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 goal 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.

goalId

string

required

Goal ID, as returned by the project's goal list.

Body

application/json

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

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

swarmRunId

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 goal'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

expectedSponsored

integer

How many of this launch's conversations you expect to be sponsored (paid from MCPJam's per-user allowance instead of your organization's credits). If the actual split differs, the launch is refused with a 409 whose details.code is swarm_funding_changed (with expectedSponsored, actualSponsored and totalConversations) and nothing is created. Omit it to accept whatever split applies.

Required range: x >= 0

Response

The run was accepted and started.

string

required

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

goalId

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 goal run 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.

funding

object

How the run's conversations are funded. sponsored conversations are paid from MCPJam's per-user allowance; the credits remainder is paid from your organization's credits. Absent when the server does not report it.

Show child attributes

⌘I

Launch a journey

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

import requests

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

payload = {
    "swarmRunId": "<string>",
    "environmentIds": ["<string>"],
    "expectedSponsored": 1
}
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({swarmRunId: '<string>', environmentIds: ['<string>'], expectedSponsored: 1})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/goals/{goalId}/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}/goals/{goalId}/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([
    'swarmRunId' => '<string>',
    'environmentIds' => [
        '<string>'
    ],
    'expectedSponsored' => 1
  ]),
  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}/goals/{goalId}/runs"

	payload := strings.NewReader("{\n  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\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}/goals/{goalId}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/goals/{goalId}/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  \"swarmRunId\": \"<string>\",\n  \"environmentIds\": [\n    \"<string>\"\n  ],\n  \"expectedSponsored\": 1\n}"

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

{
  "id": "<string>",
  "goalId": "<string>",
  "projectId": "<string>",
  "status": "running",
  "deduped": true,
  "funding": {
    "sponsored": 123,
    "credits": 123,
    "total": 123
  }
}

API Guides

Endpoints

Launch a journey

Authorizations

Headers

Path Parameters

Body

Response