Executions
View execution history, analytics, and performance metrics
The Executions resource provides access to historical execution data, performance metrics, and cost analytics for both prompts and chains.
List Executions
Retrieve a list of all prompt executions with filtering options.
const executions = await client.executions.list({
limit: 100,
status: 'success' // 'success' or 'error'
})
executions.forEach(exec => {
console.log(`${exec.promptVersion.prompt.name} v${exec.promptVersion.version}`)
console.log(` Status: ${exec.status}`)
console.log(` Latency: ${exec.latencyMs}ms`)
console.log(` Cost: $${exec.costUsd}`)
console.log(` Tokens: ${exec.tokenIn} → ${exec.tokenOut}`)
if (exec.error) {
console.log(` Error: ${exec.error}`)
}
})Get Execution Details
Retrieve complete details for a specific execution, including input, output, and metadata.
const execution = await client.executions.get('execution-id')
console.log('Execution Details:')
console.log(` Prompt: ${execution.promptVersion.prompt.name}`)
console.log(` Version: ${execution.promptVersion.version}`)
console.log(` Model: ${execution.promptVersion.model}`)
console.log(` Status: ${execution.status}`)
console.log()
console.log('Input:')
console.log(JSON.stringify(execution.input, null, 2))
console.log()
console.log('Output:')
console.log(execution.output)
console.log()
console.log('Metrics:')
console.log(` Latency: ${execution.latencyMs}ms`)
console.log(` Cost: $${execution.costUsd}`)
console.log(` Tokens: ${execution.tokenIn} in, ${execution.tokenOut} out`)
console.log(` Executed: ${new Date(execution.createdAt).toLocaleString()}`)Chain Executions
View execution history for chains, including step-by-step results.
const chainExecs = await client.executions.listChainExecutions({
chainId: 'chain-id', // Optional: filter by specific chain
limit: 50
})
chainExecs.forEach(exec => {
console.log(`Chain: ${exec.chain.name}`)
console.log(` Status: ${exec.status}`)
console.log(` Total Latency: ${exec.latencyMs}ms`)
console.log(` Total Cost: $${exec.costUsd}`)
console.log(` Steps: ${exec.steps.length}`)
exec.steps.forEach(step => {
console.log(` Step ${step.order + 1}:`)
console.log(` Latency: ${step.latencyMs}ms`)
if (step.error) {
console.log(` Error: ${step.error}`)
}
})
})Execution Statistics
Get aggregate statistics for a date range.
const stats = await client.executions.getStats({
startDate: '2024-01-01',
endDate: '2024-12-31'
})
console.log('Execution Statistics:')
console.log(` Total Executions: ${stats.totalExecutions}`)
console.log(` Successful: ${stats.successfulExecutions}`)
console.log(` Failed: ${stats.failedExecutions}`)
console.log(` Success Rate: ${stats.successRate}%`)
console.log()
console.log('Performance:')
console.log(` Average Latency: ${stats.averageLatencyMs}ms`)
console.log()
console.log('Usage:')
console.log(` Total Cost: $${stats.totalCostUsd}`)
console.log(` Total Tokens In: ${stats.totalTokensIn}`)
console.log(` Total Tokens Out: ${stats.totalTokensOut}`)Complete Example: Performance Dashboard
import Prompt Forge from '@promptforge/sdk'
const client = new Prompt Forge({
apiKey: process.env.PROMPTFORGE_API_KEY
})
async function generateDashboard() {
// Get last 30 days stats
const thirtyDaysAgo = new Date()
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)
const stats = await client.executions.getStats({
startDate: thirtyDaysAgo.toISOString(),
endDate: new Date().toISOString()
})
console.log('=== 30-Day Performance Dashboard ===')
console.log()
console.log('Execution Metrics:')
console.log(` Total Executions: ${stats.totalExecutions}`)
console.log(` Success Rate: ${stats.successRate.toFixed(2)}%`)
console.log(` Average Latency: ${stats.averageLatencyMs.toFixed(0)}ms`)
console.log()
console.log('Cost Analysis:')
console.log(` Total Spend: $${stats.totalCostUsd.toFixed(4)}`)
const avgCost = stats.totalCostUsd / stats.totalExecutions
console.log(` Avg Cost per Execution: $${avgCost.toFixed(6)}`)
console.log()
console.log('Token Usage:')
console.log(` Input Tokens: ${stats.totalTokensIn.toLocaleString()}`)
console.log(` Output Tokens: ${stats.totalTokensOut.toLocaleString()}`)
console.log(` Total Tokens: ${(stats.totalTokensIn + stats.totalTokensOut).toLocaleString()}`)
console.log()
// Get recent failures
const failures = await client.executions.list({
status: 'error',
limit: 10
})
if (failures.length > 0) {
console.log('Recent Failures:')
failures.forEach((exec, i) => {
console.log(` ${i + 1}. ${exec.promptVersion.prompt.name}`)
console.log(` Error: ${exec.error}`)
console.log(` Time: ${new Date(exec.createdAt).toLocaleString()}`)
})
} else {
console.log('No failures in recent executions')
}
}
generateDashboard()Monitoring Best Practices
Track Success Rates
Monitor your success rate over time. Sudden drops may indicate issues with prompts, models, or input data.
Monitor Costs
Keep an eye on execution costs, especially when using larger models or generating long outputs. Set up alerts for unusual spending.
Analyze Latency
Track average latency to ensure your applications meet performance requirements. Consider switching to faster models if latency becomes an issue.
Review Failures
Regularly review failed executions to identify patterns. Common issues include invalid inputs, rate limits, and prompt template errors.