List Agent Executions API

Retrieve paginated list of agent executions with advanced filtering capabilities.

Endpoint

GET /api/agents/{agentId}/executions

Authentication

Requires valid session authentication (dashboard) or API key (external API).

URL Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Unique agent identifier

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	number	No	20	Results per page (max: 100)
`offset`	number	No	0	Number of results to skip
`status`	string	No	-	Filter by execution status
`source`	string	No	-	Filter by execution source
`startDate`	string	No	-	Filter executions after this date (ISO 8601)
`endDate`	string	No	-	Filter executions before this date (ISO 8601)

Status Values

success - Execution completed successfully
failed - Execution failed with error
rate_limited - Rate limit was exceeded
canceled - User canceled the execution
unauthorized - Authentication/authorization failed

Source Values

dashboard - Executed from PrompTick dashboard
api - Executed via API
workflow - Executed as part of automated workflow

Request Examples

Basic Request

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

With Pagination

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions?limit=50&offset=100' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Filter by Status

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions?status=success' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Filter by Source

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions?source=api' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Filter by Date Range

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions?startDate=2025-11-01T00:00:00Z&endDate=2025-11-18T23:59:59Z' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Combined Filters

curl -X GET 'https://api.promptick.ai/api/agents/agent_abc123/executions?status=failed&source=api&limit=100' \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY"

Response Format

Success Response (200 OK)

{
  "executions": [
    {
      "executionId": "exec_xyz789",
      "agentId": "agent_abc123",
      "status": "success",
      "source": "api",
      "executedAt": "2025-11-18T09:45:00Z",
      "executedBy": "user_123",
      "latencyMs": 1250,
      "tokensUsed": 450,
      "costUSD": 0.0023,
      "modelUsed": "gemini-1.5-pro",
      "promptVersionLabel": "V3",
      "inputVariables": {
        "customer_name": "John Doe",
        "issue": "Account access"
      },
      "outputText": "Dear John Doe, regarding your issue with account access...",
      "apiKeyId": "key_456"
    },
    {
      "executionId": "exec_abc456",
      "agentId": "agent_abc123",
      "status": "failed",
      "source": "dashboard",
      "executedAt": "2025-11-18T09:30:00Z",
      "executedBy": "user_123",
      "latencyMs": 150,
      "tokensUsed": 0,
      "costUSD": 0,
      "modelUsed": "gemini-1.5-pro",
      "promptVersionLabel": "V3",
      "error": "Rate limit exceeded",
      "errorCode": "RATE_LIMIT_EXCEEDED"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 234,
    "hasMore": true
  }
}

Response Fields

Execution Object

Field	Type	Description
`executionId`	string	Unique execution identifier
`agentId`	string	Agent that was executed
`status`	string	Execution status (success/failed/etc)
`source`	string	Where execution originated
`executedAt`	string	ISO 8601 timestamp
`executedBy`	string	User ID who triggered execution
`latencyMs`	number	Total execution time in milliseconds
`tokensUsed`	number	Total tokens consumed
`costUSD`	number	Execution cost in USD
`modelUsed`	string	AI model used
`promptVersionLabel`	string	Prompt version label
`temperature`	number	Temperature setting used (optional)
`inputVariables`	object	Variables provided for execution
`outputText`	string	AI-generated output (if successful)
`error`	string	Error message (if failed)
`errorCode`	string	Error code (if failed)
`apiKeyId`	string	API key used (if source is 'api')

Pagination Object

Field	Type	Description
`limit`	number	Results per page
`offset`	number	Results skipped
`total`	number	Total executions matching filters
`hasMore`	boolean	Whether more results exist

Error Responses

400 Bad Request

Invalid query parameters:

{
  "error": "Invalid status value",
  "message": "Status must be one of: success, failed, rate_limited, canceled, unauthorized"
}

401 Unauthorized

Missing or invalid authentication:

{
  "error": "Unauthorized",
  "message": "Valid authentication required"
}

404 Not Found

Agent doesn't exist or not accessible:

{
  "error": "Agent not found",
  "message": "Agent with ID 'agent_abc123' not found or not accessible"
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Pagination Strategy

Basic Pagination

Fetch first page (20 results):

GET /api/agents/{agentId}/executions?limit=20&offset=0

Fetch second page:

GET /api/agents/{agentId}/executions?limit=20&offset=20

Fetch third page:

GET /api/agents/{agentId}/executions?limit=20&offset=40

Calculating Pages

const pageSize = 20;
const pageNumber = 1; // 1-indexed

const offset = (pageNumber - 1) * pageSize;
const limit = pageSize;

const url = `/api/agents/${agentId}/executions?limit=${limit}&offset=${offset}`;

Detecting Last Page

Check the hasMore field in pagination:

if (response.pagination.hasMore) {
  // More results available
  fetchNextPage();
} else {
  // This is the last page
}

Total Pages Calculation

const totalPages = Math.ceil(
  response.pagination.total / response.pagination.limit
);

Code Examples

JavaScript / Node.js

const axios = require('axios');

async function listExecutions(agentId, options = {}) {
  const params = new URLSearchParams({
    limit: options.limit || 20,
    offset: options.offset || 0,
  });

  if (options.status) params.append('status', options.status);
  if (options.source) params.append('source', options.source);
  if (options.startDate) params.append('startDate', options.startDate);
  if (options.endDate) params.append('endDate', options.endDate);

  const response = await axios.get(
    `https://api.promptick.ai/api/agents/${agentId}/executions?${params}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.PROMPTICK_API_KEY}`,
      },
    }
  );

  return response.data;
}

// Usage
const executions = await listExecutions('agent_abc123', {
  status: 'success',
  limit: 50,
});

console.log(`Found ${executions.pagination.total} successful executions`);
executions.executions.forEach(exec => {
  console.log(`${exec.executionId}: ${exec.latencyMs}ms, $${exec.costUSD}`);
});

Python

import requests
from datetime import datetime, timedelta

def list_executions(agent_id, **filters):
    params = {
        'limit': filters.get('limit', 20),
        'offset': filters.get('offset', 0),
    }

    if 'status' in filters:
        params['status'] = filters['status']
    if 'source' in filters:
        params['source'] = filters['source']
    if 'start_date' in filters:
        params['startDate'] = filters['start_date']
    if 'end_date' in filters:
        params['endDate'] = filters['end_date']

    response = requests.get(
        f'https://api.promptick.ai/api/agents/{agent_id}/executions',
        params=params,
        headers={'Authorization': f'Bearer {os.environ["PROMPTICK_API_KEY"]}'}
    )

    return response.json()

# Usage
executions = list_executions(
    'agent_abc123',
    status='failed',
    limit=100
)

print(f"Found {executions['pagination']['total']} failed executions")
for exec in executions['executions']:
    print(f"{exec['executionId']}: {exec['error']}")

cURL

#!/bin/bash

AGENT_ID="agent_abc123"
API_KEY="pk_live_YOUR_API_KEY"

# List all executions
curl -X GET "https://api.promptick.ai/api/agents/${AGENT_ID}/executions" \
  -H "Authorization: Bearer ${API_KEY}"

# List failed executions
curl -X GET "https://api.promptick.ai/api/agents/${AGENT_ID}/executions?status=failed" \
  -H "Authorization: Bearer ${API_KEY}"

# Paginate through all executions
OFFSET=0
LIMIT=50

while true; do
  RESPONSE=$(curl -s -X GET \
    "https://api.promptick.ai/api/agents/${AGENT_ID}/executions?limit=${LIMIT}&offset=${OFFSET}" \
    -H "Authorization: Bearer ${API_KEY}")

  # Process executions
  echo "$RESPONSE" | jq '.executions[]'

  # Check if more results
  HAS_MORE=$(echo "$RESPONSE" | jq -r '.pagination.hasMore')
  if [ "$HAS_MORE" = "false" ]; then
    break
  fi

  OFFSET=$((OFFSET + LIMIT))
done

Use Cases

1. Monitor Recent Failures

Check for recent failed executions:

const failures = await listExecutions('agent_abc123', {
  status: 'failed',
  limit: 10,
});

if (failures.executions.length > 0) {
  // Alert team about failures
  alertTeam(failures.executions);
}

2. Calculate Daily Costs

Sum execution costs for today:

const today = new Date().toISOString().split('T')[0];
const executions = await listExecutions('agent_abc123', {
  startDate: `${today}T00:00:00Z`,
  endDate: `${today}T23:59:59Z`,
  limit: 100,
});

const totalCost = executions.executions.reduce(
  (sum, exec) => sum + exec.costUSD,
  0
);

console.log(`Today's cost: $${totalCost.toFixed(4)}`);

3. Performance Monitoring

Track average latency over time:

const executions = await listExecutions('agent_abc123', {
  status: 'success',
  limit: 100,
});

const avgLatency =
  executions.executions.reduce((sum, exec) => sum + exec.latencyMs, 0) /
  executions.executions.length;

console.log(`Average latency: ${avgLatency.toFixed(0)}ms`);

4. Export to CSV

Export executions to CSV file:

const allExecutions = [];
let offset = 0;
const limit = 100;

// Fetch all pages
while (true) {
  const page = await listExecutions('agent_abc123', { limit, offset });
  allExecutions.push(...page.executions);

  if (!page.pagination.hasMore) break;
  offset += limit;
}

// Convert to CSV
const csv = [
  'Execution ID,Status,Source,Executed At,Latency (ms),Tokens,Cost (USD)',
  ...allExecutions.map(
    e =>
      `${e.executionId},${e.status},${e.source},${e.executedAt},${e.latencyMs},${e.tokensUsed},${e.costUSD}`
  ),
].join('\n');

fs.writeFileSync('executions.csv', csv);

Best Practices

1. Use Appropriate Pagination

Start with default page size (20)
Increase for batch processing (max 100)
Don't fetch all results if you only need recent ones

2. Filter Early

Apply filters in query parameters
Don't fetch all and filter client-side
Reduces bandwidth and improves performance

3. Handle Errors Gracefully

try {
  const executions = await listExecutions(agentId);
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Agent not found');
  } else if (error.response?.status === 429) {
    // Wait and retry
    await sleep(error.response.data.retryAfter * 1000);
    return listExecutions(agentId);
  } else {
    throw error;
  }
}

4. Cache When Appropriate

Cache results for read-heavy scenarios
Set reasonable TTL (e.g., 5 minutes)
Invalidate cache on new executions

5. Monitor Rate Limits

Track API usage
Implement exponential backoff
Use webhooks instead of polling (when available)

Execute Agent - Trigger agent execution
Get Execution Details - Get single execution
Check Status - Check execution status

Next Steps

Execution History Guide - Dashboard usage
Agent Management - Learn about agents
API Authentication - Authentication guide

Need help? Check our FAQ or contact support.

Endpoint​

Authentication​

URL Parameters​

Query Parameters​

Status Values​

Source Values​

Request Examples​

Basic Request​

With Pagination​

Filter by Status​

Filter by Source​

Filter by Date Range​

Combined Filters​

Response Format​

Success Response (200 OK)​

Response Fields​

Execution Object​

Pagination Object​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

429 Too Many Requests​

Pagination Strategy​

Basic Pagination​

Calculating Pages​

Detecting Last Page​

Total Pages Calculation​

Code Examples​

JavaScript / Node.js​

Python​

cURL​

Use Cases​

1. Monitor Recent Failures​

2. Calculate Daily Costs​

3. Performance Monitoring​

4. Export to CSV​

Best Practices​

1. Use Appropriate Pagination​

2. Filter Early​

3. Handle Errors Gracefully​

4. Cache When Appropriate​

5. Monitor Rate Limits​

Related Endpoints​

Next Steps​