Catalog

Search or list unified sessions

The unified, cross-surface sessions feed for one project: Playground, user-testing, eval, and swarm transcripts in one list, newest first. Project-NESTED (unlike /chat-sessions) because projectId owns the scope here rather than filtering it.

Supplying q at all switches to relevance-ordered search; scope then chooses what is searched. Row-level visibility applies in every mode: a caller never receives another member’s private Playground session.

The response echoes the honored scope. A deployment predating that parameter omits the echo — clients requesting a non-default scope MUST treat its absence as “unsupported” rather than accepting the results.

GET

projects

{projectId}

sessions

Search or list unified sessions

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/sessions \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/sessions', 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}/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "items": [
    {
      "id": "<string>",
      "chatSessionId": "<string>",
      "projectId": "<string>",
      "origin": "<string>",
      "status": "<string>",
      "synthetic": true,
      "lockReason": "<string>",
      "title": "<string>",
      "firstMessagePreview": "<string>",
      "visibility": "<string>",
      "ownedByViewer": true,
      "startedAt": 123,
      "lastActivityAt": 123,
      "modelId": "<string>",
      "messageCount": 123,
      "parentRef": {
        "label": "<string>",
        "iterationId": "<string>",
        "suiteRunId": "<string>",
        "suiteId": "<string>",
        "journeyRunId": "<string>",
        "journeyRefId": "<string>",
        "chatboxId": "<string>"
      },
      "link": {
        "path": "<string>",
        "url": "<string>"
      },
      "cumulativeUserMessageCount": 123,
      "cumulativeToolCallCount": 123,
      "cumulativeInputTokens": 123,
      "cumulativeOutputTokens": 123,
      "matchPreview": "<string>"
    }
  ],
  "nextCursor": "<string>"
}

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.

Query Parameters

string

Search terms. Supplying this at all switches from the recency feed to relevance-ordered search; q= (blank) is an empty search, not "no filter".

scope

enum<string>

default:titles

What to search. titles (default) matches titles and opening messages; transcripts matches conversation content. Requires q; an unknown value is a 400.

Available options:

titles,

transcripts

sourceType

string

Comma-separated surfaces to include: direct, chatbox, eval, swarm. Omit for all. An unknown value is a 400 rather than a silent widening.

status

enum<string>

default:active

active (default) or archived.

Available options:

active,

archived

limit

integer

default:50

Page size, 1–200. Defaults to 50.

Required range: 1 <= x <= 200

cursor

string

Opaque cursor: echo back the previous page's nextCursor. Never construct one, and never assume it encodes a timestamp. Cursors do not cross scopes — page with the parameters you opened with.

Response

One page of sessions — newest first when listing, most relevant first when searching.

items

object[]

required

Show child attributes

nextCursor

string

Pass as cursor to fetch the next page. Omitted on the last page.

scope

enum<string>

The scope the server actually honored. ABSENT from deployments predating the parameter — treat its absence as "transcript search unsupported".

Available options:

titles,

transcripts

⌘I

Search or list unified sessions

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/sessions \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/sessions', 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}/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "items": [
    {
      "id": "<string>",
      "chatSessionId": "<string>",
      "projectId": "<string>",
      "origin": "<string>",
      "status": "<string>",
      "synthetic": true,
      "lockReason": "<string>",
      "title": "<string>",
      "firstMessagePreview": "<string>",
      "visibility": "<string>",
      "ownedByViewer": true,
      "startedAt": 123,
      "lastActivityAt": 123,
      "modelId": "<string>",
      "messageCount": 123,
      "parentRef": {
        "label": "<string>",
        "iterationId": "<string>",
        "suiteRunId": "<string>",
        "suiteId": "<string>",
        "journeyRunId": "<string>",
        "journeyRefId": "<string>",
        "chatboxId": "<string>"
      },
      "link": {
        "path": "<string>",
        "url": "<string>"
      },
      "cumulativeUserMessageCount": 123,
      "cumulativeToolCallCount": 123,
      "cumulativeInputTokens": 123,
      "cumulativeOutputTokens": 123,
      "matchPreview": "<string>"
    }
  ],
  "nextCursor": "<string>"
}

API Guides

Endpoints

Search or list unified sessions

Authorizations

Path Parameters

Query Parameters

Response