Read Workflow

This workflow retrieves backtest results from the platform. You'll learn how to list strategies, view scenarios, and download results in various formats.

Overview

The read workflow follows these steps:

1. List strategies - See all your trading strategies
2. List scenarios - See backtests for a specific strategy
3. Download results - Get metadata, timeseries, or trade data

Prerequisites

Before starting, ensure you have:

• The Tektii CLI installed (Installation)
• Your API key configured (Authentication)

Step 1: List Your Strategies

First, view all your strategies to find the one you want to analyze:

tektii strategy list

This displays a table with your strategies:

┌──────────────────┬─────────────┬──────────────┬────────────┬─────────────┐
│ ID               │ Name        │ Owner        │ Created    │ Best Return │
├──────────────────┼─────────────┼──────────────┼────────────┼─────────────┤
│ a1b2c3d4-e5f6...  │ momentum-v1 │ user_9f2c... │ 2024-01-15 │ 12.45%      │
│ f6a7b8c9-d0e1...  │ mean-revert │ user_9f2c... │ 2024-01-10 │ N/A         │
└──────────────────┴─────────────┴──────────────┴────────────┴─────────────┘

Pagination

For large lists, use pagination:

# Limit to 10 results
tektii strategy list --limit 10

# Get next page using cursor from previous response
tektii strategy list --cursor "eyJsYXN0X2lkIjoi..."

JSON Output

For scripting or piping to other tools, use JSON output:

tektii --output json strategy list | jq '.strategies[0].id'

Step 2: List Scenarios for a Strategy

Once you have a strategy ID, list its backtest scenarios:

tektii scenario list a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

This shows all backtests run against that strategy:

┌──────────────────┬──────────────────┬──────────────────────────┬─────────────────┬──────────┬────────┐
│ Scenario ID      │ Version           │ Period                   │ Subscriptions   │ State    │ Return │
├──────────────────┼──────────────────┼──────────────────────────┼─────────────────┼──────────┼────────┤
│ c3d4e5f6-a7b8...  │ b2c3d4e5-f6a7...  │ 2024-01-01 to 2024-06-30 │ 1 subscriptions │ COMPLETE │ 12.45% │
│ 7c8d9e0f-1a2b...  │ 9e0f1a2b-3c4d...  │ 2024-01-01 to 2024-06-30 │ 2 subscriptions │ COMPLETE │ -3.20% │
└──────────────────┴──────────────────┴──────────────────────────┴─────────────────┴──────────┴────────┘

The State column is uppercase — QUEUED, PENDING, RUNNING, COMPLETE, FAILED, or CANCELLED. A freshly submitted run starts at QUEUED (enqueued, awaiting dispatch). In JSON output (--output json) this is the state field.

Pagination works the same way:

tektii scenario list a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --limit 5 --cursor "..."

Step 3: Download Results

With both strategy and scenario IDs, download the backtest results. (Prefer a visual read? Every completed scenario is also viewable in the web app, with the equity curve and metrics rendered as charts — the downloads below are for local analysis and tooling.)

View Metadata

By default, scenario download displays metadata in your terminal:

tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

Output:

┌─────────────────────┬────────────────────────────────────────┐
│ Metric              │ Value                                  │
├─────────────────────┼────────────────────────────────────────┤
│ ID                  │ c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f    │
│ Starting Capital    │ $100,000                                │
│ Final Capital       │ $112,450                                │
│ Total Return %      │ 12.45%                                  │
│ Duration            │ 365 days                                │
│ Trades              │ 142 (0 open)                            │
│ Trades per Day      │ 0.39                                    │
│ Data Points         │ 525,600                                 │
└─────────────────────┴────────────────────────────────────────┘

Download Metadata to a File

Save the metadata to a file:

tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --file metadata.json

When you pass --file, metadata is always saved as JSON — the --format flag only changes how metadata is rendered in the terminal, not how it is written to disk.

Download Timeseries Data

Get the full equity curve and performance timeseries:

tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type timeseries \
  --file timeseries.json

Download Trade Log

Get detailed information about every trade:

tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type trades \
  --file trades.json

Download Raw Compressed Data

For maximum efficiency, download the original Zstandard-compressed data:

tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type timeseries \
  --raw \
  --file timeseries.json.zst

Complete Example

Here's the full workflow from start to finish:

# Step 1: List your strategies
tektii strategy list

# Step 2: List scenarios for a strategy
tektii scenario list a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

# Step 3: View backtest metadata
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

# Step 4: Download full timeseries data
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type timeseries \
  --file results.json

# Step 5: Download trade log
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type trades \
  --file trades.json

Command Reference

Result Types

Output Flags

These flags apply to scenario download. Pagination (page size and cursors) is controlled separately on the list commands — see Pagination above.

Next Steps

• Results Reference - Every field in timeseries.json and trades.json, plus how each headline metric is computed
• Write Workflow - Push Docker images as strategy versions
• Troubleshooting - Common errors and fixes