Swarm insights

Request wave insights

Answers 202: generation is scheduled, not done. Poll the GET above rather than re-requesting.

SPENDS. This runs models on your organization’s account and draws on the insightsPerDay ledger, which is SHARED with eval-run and user-testing insights — burning it here takes it from there too.

Three refusals, and they mean different things:

429 with code: "RATE_LIMITED" and a short Retry-After — the per-minute burst brake. Wait seconds.
429 naming insightsPerDay in details — the daily ledger. Retry-After counts to UTC midnight.
403 — the feature is not available to your organization. Waiting will never help; collapsing this into the 429s would send someone who hit today’s cap shopping for a plan they already have.

POST

projects

{projectId}

waves

{waveId}

insights

Request wave insights

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": true
}'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights"

payload = { "force": True }
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({force: true})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights', 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}/waves/{waveId}/insights",
  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([
    'force' => true
  ]),
  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}/waves/{waveId}/insights"

	payload := strings.NewReader("{\n  \"force\": true\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}/waves/{waveId}/insights")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights")

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  \"force\": true\n}"

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

{
  "waveId": "<string>",
  "projectId": "<string>",
  "status": "pending"
}

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.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

waveId

string

required

Wave ID — the opaque group id shared by every run of one co-launched swarm. Returned on every run in the wave.

Body

application/json

Optional. Omit the body entirely for the common case.

force

boolean

Regenerate over a wave that already has insights. OFF by default because it SPENDS a second time against your organization's shared daily ledger — and the common cause of a repeated request is a caller that did not poll.

Response

Generation was scheduled.

waveId

string

required

projectId

string

required

status

enum<string>

required

Available options:

pending

⌘I

Request wave insights

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "force": true
}'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights"

payload = { "force": True }
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({force: true})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights', 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}/waves/{waveId}/insights",
  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([
    'force' => true
  ]),
  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}/waves/{waveId}/insights"

	payload := strings.NewReader("{\n  \"force\": true\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}/waves/{waveId}/insights")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/waves/{waveId}/insights")

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  \"force\": true\n}"

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

{
  "waveId": "<string>",
  "projectId": "<string>",
  "status": "pending"
}

API Guides

Endpoints

Request wave insights

Authorizations

Path Parameters

Body

Response