Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Guides

Tasks and sessions

Mubit finds tasks in your calls by itself. This page shows what decides a call's task, and how to tell Mubit which calls belong to one conversation.

What makes a task

Calls form one task when they share all of these:

  • their instructions;
  • their tools;
  • their tool choice;
  • their output format;
  • their model.

The rest of the call doesn't count: the messages after the instructions, and settings such as temperature or max_tokens. For the model, see Keep your model IDs.

The instructions are the system prompt: system on Anthropic; the system and developer messages on OpenAI Chat Completions; instructions and the system and developer input items on OpenAI Responses; systemInstruction on Gemini.

Tasks shows each task under a short name made from the first words of its instructions.

Mubit reads the instructions with a few allowances, so one kind of call keeps one task:

  • Runs of spaces and line breaks count as one space.
  • Numbers, dates, times and IDs don't split a task.
  • Other words that change from call to call do: a customer's name in the instructions makes one task per name.
💡Tip

Put the text that changes per call, such as a name, in the user message, not in the instructions.

Group a conversation's calls into a session

A session is the calls of one conversation. Mubit sets a task's test cases aside by session.

Mubit gives each call a session. It takes the first of these that the call has:

  1. metadata.thread_id
  2. metadata.session_id
  3. metadata.conversation_id
  4. On Anthropic, metadata.user_id
  5. On OpenAI Responses, prompt_cache_key

A call with none of these gets a session from the start of its conversation: its instructions and its first user message. When each call sends the conversation so far, its later turns repeat them, so its calls share a session without any field. If your app sends only the new message, for example with Responses' previous_response_id, send metadata.session_id.

Which field to send:

ProviderField
OpenAImetadata.session_id, or metadata.thread_id or metadata.conversation_id
Anthropicmetadata.user_id, the one metadata field Anthropic takes
GeminiNone: Mubit uses the start of the conversation

On Anthropic, if your app already sends metadata.user_id as an ID for your end user, all of that user's conversations become one session.

Mubit trims each value. A value longer than 200 characters is kept as a hash.

Example

This call names its session ticket-1042:

Python
import os
from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.mubit.ai/openai/v1",
    api_key=os.environ["MUBIT_API_KEY"],
)
 
instructions = (
    "Sort the support message into one category: "
    "billing, bug, account or other. Reply with the category only."
)
 
response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[
        {"role": "system", "content": instructions},
        {"role": "user", "content": "I cannot sign in since I changed my email address."},
    ],
    metadata={"session_id": "ticket-1042"},
)
print(response.choices[0].message.content)

The TypeScript example uses top-level await, so run it as an ES module: save the file as tasks.mts and run npx tsx tasks.mts, or add "type": "module" to your package.json.

See a call's session

  1. In the console, open Requests.
  2. Select the call's row.
  3. Open Details. Session shows the call's session.

To list one session's calls, enter its ID in the Session filter on Requests. See Find calls in Requests.

If a call fails

The error names its code. Troubleshooting lists the codes and what to do.