Skip to main content

​
Overview

Retrieves the conversation history for a workflow session, including user messages, AI responses, build logs, and error messages. Essential for debugging, reviewing progress, and understanding what happened during a build.
Messages are stored per-session and include both human instructions and AI responses.

​
Parameters

​
session_id
string
required
Session ID to get messages for
  • Format: UUID
  • Get it from: bilt_get_session
  • Example: "550e8400-e29b-41d4-a716-446655440000"
​
limit
number
default:"50"
Maximum number of messages to return
  • Range: 1-100
  • Default: 50
  • Example: 20
​
offset
number
default:"0"
Number of messages to skip (for pagination)
  • Default: 0
  • Example: 50 (to get next page)

​
Response

​
messages
array
required
Array of message objects, newest first
​
total
number
required
Total number of messages in session
​
has_more
boolean
required
Whether more messages exist (for pagination)

​
Example Usage

​
Get Recent Messages

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 10
}

​
Get All Messages (Pagination)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 50,
  "offset": 0
}

​
Message Variants

infoInformational messages (progress updates, status changes)

successSuccessful operations (build complete, deployed)

errorErrors and failures (build failed, deployment error)

logDebug logs and detailed output

​
Common Use Cases

​
Debug Build Failures

User: "Why did my build fail?"

Agent workflow:
1. Call bilt_get_session() to get session_id
2. Call bilt_get_messages(session_id, limit: 20)
3. Filter for variant === "error"
4. Analyze error messages
5. Explain to user

​
Review Build History

User: "What did we build in this session?"

Agent workflow:
1. Call bilt_get_messages(session_id)
2. Extract user messages (side === "user")
3. Summarize: "You asked for: login page, dark mode, and deployment"

​
Get Deployment URL

Agent workflow:
1. Call bilt_get_messages(session_id, limit: 10)
2. Find latest AI message with "Deployed to"
3. Extract URL from message
4. Return to user

​
Show Build Logs

User: "Show me the build logs"

Agent workflow:
1. Call bilt_get_messages(session_id, limit: 100)
2. Filter for variant === "log"
3. Display in chronological order

​
Pagination Example

async function getAllMessages(sessionId) {
  const allMessages = [];
  let offset = 0;
  const limit = 50;
  
  while (true) {
    const response = await bilt_get_messages({
      session_id: sessionId,
      limit,
      offset
    });
    
    allMessages.push(...response.messages);
    
    if (!response.has_more) {
      break;
    }
    
    offset += limit;
  }
  
  return allMessages;
}

​
Filtering Messages

// Get only errors
const { messages } = await bilt_get_messages({ session_id });
const errors = messages.filter(m => m.variant === 'error');

// Get only user messages
const userMessages = messages.filter(m => m.side === 'user');

// Get messages from specific workflow
const workflowMessages = messages.filter(
  m => m.workflow_id === 'wf_abc123'
);

// Get recent successes
const successes = messages
  .filter(m => m.variant === 'success')
  .slice(0, 5);

​
Best Practices

Use appropriate limit values:
// For recent activity
await bilt_get_messages({ session_id, limit: 10 });

// For debugging
await bilt_get_messages({ session_id, limit: 50 });

// For full history
await bilt_get_messages({ session_id, limit: 100 });
When debugging, look for errors immediately:
const { messages } = await bilt_get_messages({ session_id });
const errors = messages.filter(m => m.variant === 'error');

if (errors.length > 0) {
  console.log('Found errors:', errors);
}
Format messages for user readability:
Agent: "Here's what happened:

15:20 - You: Add login page
15:21 - Bilt: Building login component...
15:23 - Bilt: ✓ Login page created
15:25 - You: Deploy
15:26 - Bilt: ✓ Deployed to https://app.bilt.me"
Don’t try to fetch all messages at once if there are hundreds:
// Check total first
const first = await bilt_get_messages({ 
  session_id, 
  limit: 1 
});

if (first.total > 100) {
  // Use pagination
}

​
Error Handling

{
  "error": "Invalid or expired API key"
}

​
Performance

Response Time< 200ms for 50 messages

Payload Size~100-200 bytes per message

RetentionMessages stored for 90 days

​
Message Ordering

Messages are returned newest first (reverse chronological): 
[
  { "timestamp": "15:30:00", "message": "Latest" },
  { "timestamp": "15:25:00", "message": "Middle" },
  { "timestamp": "15:20:00", "message": "Oldest" }
]
To display in chronological order, reverse the array: 
const { messages } = await bilt_get_messages({ session_id });
const chronological = messages.reverse();

bilt_get_session

Get session status

bilt_send_message

Add new messages

bilt_cancel_workflow

Stop workflow

​
Next Steps

After reviewing messages:
  1. Debug errors - Analyze error messages and fix issues
  2. Continue workflow - Use bilt_send_message
  3. Check status - Use bilt_get_session