The Timeline API provides endpoints to retrieve and manage execution timeline data. It supports pagination, real-time updates, and change tracking for execution records.

​
Overview

The timeline system tracks executions with the following key features:
  • Pagination: Load results in configurable page sizes
  • Real-time updates: Track changes since a specific timestamp
  • Search filtering: Filter results by various criteria
  • Change detection: Identify new, modified, and deleted executions

​
Endpoints

​
GET /timeline/list

Retrieves paginated timeline results sorted from the specified offset. This endpoint is optimized for traditional pagination workflows. Query Parameters:
  • pp (optional): Page size, defaults to 10
  • q (optional): Search query string for filtering results
  • offset (optional): Execution ID to start pagination from
Response: 
{
  "items": [
    {
      "fid": "20241201T120000Z",
      "tags": ["production", "batch"],
      "summary": "Data processing job",
      "inputs": {...},
      "status": "completed",
      "startup": "2024-12-01T12:00:00",
      "finish": "2024-12-01T12:15:30",
      "runtime": 930.5,
      "locks": []
    }
  ],
  "query": "search term",
  "offset": "20241130T150000Z"
}

​
GET /timeline/changes

Retrieves changes to timeline items since a given timestamp. This endpoint is designed for real-time updates and change tracking. Query Parameters:
  • since (optional): Unix timestamp to check for changes since
  • q (optional): Search query string for filtering results
Response: 
{
  "update": [
    {
      "fid": "20241201T120000Z",
      "tags": ["production", "batch"],
      "summary": "Data processing job",
      "inputs": {...},
      "status": "running",
      "startup": "2024-12-01T12:00:00",
      "finish": null,
      "runtime": null,
      "locks": ["lock_123"]
    }
  ],
  "delete": ["20241130T150000Z"],
  "timestamp": 1701432000.0,
  "query": "search term"
}
Special Behavior:
  • If no since parameter is provided, returns only the current maximum modification timestamp
  • This allows clients to establish a baseline timestamp for future change requests

​
Data Model

​
Execution Record Fields

Each execution record contains the following fields:
FieldTypeDescription
fidstringExecution ID (timestamp-based)
tagsarrayArray of execution tags
summarystringBrief description of the execution
inputsobjectInput data and configuration
statusstringCurrent execution status
startupdatetimeExecution start time
finishdatetimeExecution completion time
runtimefloatTotal execution time in seconds
locksarrayActive lock identifiers

​
Search Fields

The search functionality supports filtering by:
  • author: Execution author
  • organization: Organization name
  • summary: Execution summary text
  • description: Detailed description
  • fid: Execution ID
  • status: Execution status
  • tags: Individual tag values
  • startup: Start time
  • inputs: Input data
  • final: Final results

​
Usage Examples

​
Basic Pagination

// Get first page of executions
const response = await fetch('/timeline/list?pp=20');
const data = await response.json();

// Get next page using offset
const nextPage = await fetch(`/timeline/list?pp=20&offset=${data.offset}`);

​
Real-time Updates

// Get initial timestamp
const baseline = await fetch('/timeline/changes');
const timestamp = baseline.timestamp;

// Poll for changes
setInterval(async () => {
  const changes = await fetch(`/timeline/changes?since=${timestamp}`);
  const data = await changes.json();
  
  if (data.update.length > 0 || data.delete.length > 0) {
    // Handle updates
    console.log('New changes:', data);
  }
}, 5000);

​
Search and Filter

// Search for production jobs
const results = await fetch('/timeline/list?q=production&pp=50');

// Search for specific author
const authorResults = await fetch('/timeline/list?q=author:john.doe');

​
Error Handling

The API returns appropriate HTTP status codes:
  • 200: Successful response
  • 400: Invalid parameters
  • 401: Unauthorized (user not authenticated)
  • 500: Internal server error