Chat sessions

Read a chat session's execution trace

Per-turn execution spans: per-tool-call latency, token usage, and indices into the transcript. Same span shape as the eval iteration trace.

Incremental by default — returns the LATEST turn, not the whole session, because a session’s spans are the largest thing this API emits and the turn you just took is the one you are debugging. Reach older turns with turnId or afterPromptIndex; use includeSpans=false for cheap per-turn summaries.

A turn whose spans could not be read reports spansUnavailable: true rather than an empty spans array: “made no calls” and “could not fetch” are opposite conclusions.

GET

chat-sessions

{sessionId}

trace

Read a chat session's execution trace

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

import requests

url = "https://app.mcpjam.com/api/v1/chat-sessions/{sessionId}/trace"

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/chat-sessions/{sessionId}/trace', 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/chat-sessions/{sessionId}/trace",
  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/chat-sessions/{sessionId}/trace"

	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/chat-sessions/{sessionId}/trace")

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

{
  "sessionId": "<string>",
  "origin": "<string>",
  "traceVersion": 1,
  "turnCount": 123,
  "turns": [
    {
      "turnId": "<string>",
      "promptIndex": 123,
      "startedAt": 123,
      "endedAt": 123,
      "spanCount": 123,
      "finishReason": "<string>",
      "modelId": "<string>",
      "usage": {
        "inputTokens": 123,
        "outputTokens": 123,
        "totalTokens": 123
      },
      "spans": [
        {}
      ],
      "spansUnavailable": true,
      "spansTruncated": true
    }
  ],
  "latestPromptIndex": 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.

Path Parameters

sessionId

string

required

The chat session's id — the same id POST /chat-sessions/messages returns and GET /chat-sessions lists.

Query Parameters

projectId

string

Optional project scope. When set, a session in another project answers 404 — the same answer as absence, so this is never an existence oracle.

turnId

string

Return exactly this turn. Mutually exclusive with afterPromptIndex.

afterPromptIndex

integer

Page forward from this turn index. Mutually exclusive with turnId.

Required range: x >= 0

limit

integer

default:1

Turns to return, 1–20. Defaults to 1 (the latest).

Required range: 1 <= x <= 20

includeSpans

boolean

default:true

Set false for per-turn summaries without span payloads.

Response

The selected turns, ascending by promptIndex.

sessionId

string

required

origin

string | null

required

traceVersion

enum<integer>

required

Available options:

1

turnCount

integer

required

Turns the session has in total, so a caller can tell whether the window is the whole story.

turns

object[]

required

Show child attributes

latestPromptIndex

integer

⌘I

Read a chat session's execution trace

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

import requests

url = "https://app.mcpjam.com/api/v1/chat-sessions/{sessionId}/trace"

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/chat-sessions/{sessionId}/trace', 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/chat-sessions/{sessionId}/trace",
  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/chat-sessions/{sessionId}/trace"

	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/chat-sessions/{sessionId}/trace")

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

{
  "sessionId": "<string>",
  "origin": "<string>",
  "traceVersion": 1,
  "turnCount": 123,
  "turns": [
    {
      "turnId": "<string>",
      "promptIndex": 123,
      "startedAt": 123,
      "endedAt": 123,
      "spanCount": 123,
      "finishReason": "<string>",
      "modelId": "<string>",
      "usage": {
        "inputTokens": 123,
        "outputTokens": 123,
        "totalTokens": 123
      },
      "spans": [
        {}
      ],
      "spansUnavailable": true,
      "spansTruncated": true
    }
  ],
  "latestPromptIndex": 123
}

API Guides

Endpoints

Read a chat session's execution trace

Authorizations

Path Parameters

Query Parameters

Response