Examples

End-to-end examples covering the most common API workflows. All examples use curl — adapt to your preferred HTTP client or language.

Replace qapi_... with your actual API token from Console → Account → API Tokens.

export QUANTINAL_TOKEN="qapi_your_token"

List Your Spaces

Retrieve all spaces in your account.

curl https://api.quantinal.ai/v1/api/spaces \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Create a Tracker

Create a manual tracker to monitor Tesla stock sentiment. Trackers are created under a space using the nested URL.

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_your-space-id/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tesla Sentiment",
    "description": "Tracks Tesla stock sentiment from news and social media",
    "run_mode": "manual",
    "agent_config": {
      "instruction": "Analyze Tesla (TSLA) considering recent news, analyst reports, social media sentiment, and price momentum.",
      "score_meaning": "Market Sentiment",
      "skills": ["financial_markets"],
      "reasoning_mode": "basic"
    }
  }'

Create a Scheduled Tracker

Create a tracker that runs automatically every 24 hours with email notifications when scores drop below 30.

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Market Pulse",
    "description": "Daily overview of S&P 500 sentiment",
    "run_mode": "scheduled",
    "agent_config": {
      "instruction": "Analyze the overall market sentiment for the S&P 500 index using major financial news sources and recent economic data releases.",
      "score_meaning": "Market Sentiment",
      "skills": ["financial_markets"],
      "reasoning_mode": "advanced"
    },
    "schedule": {
      "start_time": "2026-03-18T09:00:00Z",
      "interval_minutes": 1440
    },
    "notification_config": {
      "score_threshold": 30,
      "email_enabled": true
    }
  }'

Create a Tracker with Linked Trackers

Link same-space trackers and starred public trackers so their latest results are fed to your agent as context. Each linked tracker adds to per-run cost — see pricing.

Link to same-space trackers

If you already have sector-specific trackers (e.g. energy, tech) in the same space, reference them by tracker_id:

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portfolio Risk Monitor",
    "description": "Aggregates sector scores to assess overall portfolio risk",
    "run_mode": "manual",
    "agent_config": {
      "instruction": "Evaluate overall portfolio risk by synthesizing results from the linked sector trackers. Highlight correlations, divergences, and any conflicting scores.",
      "score_meaning": "Portfolio Risk Level",
      "skills": ["financial_markets"],
      "reasoning_mode": "advanced",
      "linked_trackers": ["trk_e4f5a6b7-1c2d-4e3f-a4b5-c6d7e8f9a0b1", "trk_c8d9e0f1-2a3b-4c4d-5e6f-7a8b9c0d1e2f"]
    }
  }'

Link to starred public trackers

Star a public tracker in the Console first, then reference its tracker_id:

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Macro-Aware Tesla Tracker",
    "description": "Tesla analysis enriched with a marketplace macro tracker",
    "run_mode": "manual",
    "agent_config": {
      "instruction": "Analyze Tesla (TSLA) stock, incorporating the macro economic score from the linked public tracker as broader market context.",
      "score_meaning": "Market Sentiment",
      "skills": ["financial_markets", "web"],
      "reasoning_mode": "basic",
      "linked_trackers": ["trk_b7a6c5d4-3e2f-41a0-b9c8-d7e6f5a4b3c2"]
    }
  }'

Mix both types

You can combine same-space and starred public trackers (up to 10 total):

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Full-Stack Research",
    "description": "Combines internal sector trackers with marketplace macro scores",
    "run_mode": "scheduled",
    "agent_config": {
      "instruction": "Produce a comprehensive daily research brief using results from linked sector trackers and the public macro tracker.",
      "score_meaning": "Research Confidence",
      "skills": ["financial_markets", "web"],
      "reasoning_mode": "advanced",
      "linked_trackers": ["trk_e4f5a6b7-1c2d-4e3f-a4b5-c6d7e8f9a0b1", "trk_c8d9e0f1-2a3b-4c4d-5e6f-7a8b9c0d1e2f", "trk_b7a6c5d4-3e2f-41a0-b9c8-d7e6f5a4b3c2"]
    },
    "schedule": {
      "start_time": "2026-03-20T09:00:00Z",
      "interval_minutes": 1440
    }
  }'

info

Same-space trackers can be linked directly.
Public trackers must be starred in the Console before they can be linked via the API.
Private trackers are free; public trackers cost +0.016q each (includes creator commission).

Update a Tracker to Add Linked Trackers

Add linked trackers to an existing tracker by updating its agent_config. Send the complete agent_config object — all fields are replaced as a unit.

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "instruction": "Analyze Tesla (TSLA) considering recent news, analyst reports, social media sentiment, price momentum, and results from linked sector trackers.",
      "score_meaning": "Market Sentiment",
      "skills": ["financial_markets"],
      "reasoning_mode": "basic",
      "linked_trackers": ["trk_a0b1c2d3-4e5f-46a7-b8c9-d0e1f2a3b4c5", "trk_b7a6c5d4-3e2f-41a0-b9c8-d7e6f5a4b3c2"]
    }
  }'

To remove all linked trackers, set the array to empty:

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "instruction": "Analyze Tesla (TSLA) considering recent news, analyst reports, social media sentiment, and price momentum.",
      "score_meaning": "Market Sentiment",
      "skills": ["financial_markets"],
      "reasoning_mode": "basic",
      "linked_trackers": []
    }
  }'

Run a Tracker (Sync)

Trigger a run and wait for the result in a single request.

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sync": true}'

The response includes the full result:

{
  "run_id": "run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "completed",
  "started_at": "2026-02-18T10:00:00Z",
  "completed_at": "2026-02-18T10:00:45Z",
  "execution_time_seconds": 45.2,
  "result": {
    "score": 72,
    "insight": "Tesla sentiment is moderately bullish...",
    "baseline_score": 66,
    "score_adjustment_factors": [
      { "factor": "Earnings momentum", "impact": 12, "probability": 0.7 },
      { "factor": "Macro uncertainty", "impact": -6, "probability": 0.4 }
    ]
  },
  "error_message": null
}

baseline_score and score_adjustment_factors are optional. When present, they explain how the final score moved from baseline using deterministic factor scoring.

Run a Tracker (Async + Poll)

Trigger a run asynchronously, then poll for the result.

Step 1 — Trigger

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Returns 202 Accepted with a run_id:

{
  "run_id": "run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "pending",
  "created_at": "2026-02-18T10:00:00Z"
}

Step 2 — Poll until completed

curl https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs/run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Repeat until "status": "completed".

Create a Tracker with a Shared Vault

Create a tracker that shares another tracker's vault. Both trackers will read and write to the same vault data. Provide the target tracker's ID as shared_vault_tracker_id.

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portfolio Risk Analysis",
    "description": "Analyze portfolio risk using shared company data",
    "run_mode": "manual",
    "agent_config": {
      "instruction": "Assess overall portfolio risk from the uploaded company data. Focus on sector concentration and earnings trends.",
      "score_meaning": "Portfolio Risk Level",
      "skills": ["financial_markets"],
      "reasoning_mode": "advanced"
    },
    "shared_vault_tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }'

The response confirms vault sharing:

{
  "tracker_id": "trk_e5f6a7b8-9c0d-41e2-f3a4-b5c6d7e8f9a0",
  "shared_vault_tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  ...
}

tip

Just pass the tracker ID of the tracker whose vault you want to share — no need to look up a separate vault ID.

Revert a Tracker to Its Own Vault

To stop sharing and go back to the tracker's own vault, set shared_vault_tracker_id to null:

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_e5f6a7b8-9c0d-41e2-f3a4-b5c6d7e8f9a0 \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shared_vault_tracker_id": null}'

No data is moved or copied. The shared vault keeps its data, and the tracker's own vault still has whatever was there before sharing.

Upload Data to Tracker Vault

Upload a File

Upload a PDF report as private context for the tracker's agent.

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -F "file=@earnings-report.pdf" \
  -F "source_name=Q4 Earnings Report"

Upload JSON Data

Push structured data (single record or batch) to the vault.

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_name": "earnings-data",
    "data": [
      {"ticker": "AAPL", "eps": 1.53, "date": "2025-Q4"},
      {"ticker": "MSFT", "eps": 3.23, "date": "2025-Q4"},
      {"ticker": "GOOGL", "eps": 2.12, "date": "2025-Q4"}
    ]
  }'

List and Filter Runs

Get All Completed Runs

curl "https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs?status=completed" \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Filter by Score Range and Date

Retrieve only low-scoring runs (below 3.0) from the past week.

curl "https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs?min_score=0&max_score=30&start_date=2026-03-10T00:00:00Z&end_date=2026-03-17T23:59:59Z" \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Filter by Score Range

Get runs with scores between 10 and 30 (bearish results).

curl "https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs?min_score=10&max_score=30" \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Get Recent Vault Data

Fetch the latest data items added to a tracker's vault in the last 24 hours.

curl "https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/recent?limit=10&since_hours=24" \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Update a Tracker

Change a tracker from manual to scheduled mode.

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "run_mode": "scheduled",
    "schedule": {
      "start_time": "2026-03-18T09:00:00Z",
      "interval_minutes": 360
    }
  }'

Delete Resources

Add or Update Run Comment

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs/run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Great signal this run. Watch macro exposure on the next cycle."}'

Clear Run Comment

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs/run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f \
  -H "Authorization: Bearer $QUANTINAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment":null}'

Delete a Run

curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/runs/run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Delete a Data Source

curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources/b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

Delete a Tracker

curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $QUANTINAL_TOKEN"

caution

Delete operations are permanent and irreversible. Deleting a tracker also removes all its runs, results, vault, and data sources. If the tracker's vault is shared by other trackers, deletion is blocked (409 Conflict) — those trackers must set shared_vault_tracker_id to null first.

List Your Spaces​

Create a Tracker​

Create a Scheduled Tracker​

Create a Tracker with Linked Trackers​

Link to same-space trackers​

Link to starred public trackers​

Mix both types​

Update a Tracker to Add Linked Trackers​

Run a Tracker (Sync)​

Run a Tracker (Async + Poll)​

Create a Tracker with a Shared Vault​

Revert a Tracker to Its Own Vault​

Upload Data to Tracker Vault​

Upload a File​

Upload JSON Data​

List and Filter Runs​

Get All Completed Runs​

Filter by Score Range and Date​

Filter by Score Range​

Get Recent Vault Data​

Update a Tracker​

Delete Resources​

Add or Update Run Comment​

Clear Run Comment​

Delete a Run​

Delete a Data Source​

Delete a Tracker​