Endpoints

All available API endpoints are listed below, grouped by resource.

---

Spaces

Project containers for trackers and results. Learn more →

Space Management is Read-Only via API

API tokens can list and get spaces. To create, update, or delete spaces, use the web console.

GET /api/spaces

List all your spaces with aggregated counts for trackers, sources, and results.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request

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

Response (200 OK)

{
  "data": [
    {
      "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
      "name": "Market Research",
      "description": "Tracking financial markets",
      "category": "finance",
      "capacity_gb": 10,
      "throughput_per_hour": 600,
      "used_gb": 2.4,
      "monthly_cost": 5.5,
      "storage_cost": 2.5,
      "throughput_cost": 3.0,
      "rate_limit_per_hour": 600,
      "tracker_count": 5,
      "source_count": 3,
      "result_count": 142,
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 1,
    "total_pages": 1
  }
}

---

GET /api/spaces/{space_id}

Get details for a specific space including capacity, usage, and resource counts.

Path Parameters

Parameter	Type	Required	Description
space_id	string	Yes	Space ID

Request

curl https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7 \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)

{
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "Market Research",
  "description": "Tracking financial markets",
  "category": "finance",
  "capacity_gb": 10,
  "throughput_per_hour": 600,
  "used_gb": 2.4,
  "monthly_cost": 5.5,
  "storage_cost": 2.5,
  "throughput_cost": 3.0,
  "rate_limit_per_hour": 600,
  "is_active": true,
  "tracker_count": 5,
  "source_count": 3,
  "result_count": 142,
  "created_at": "2026-01-15T08:00:00Z",
  "updated_at": "2026-02-10T14:30:00Z"
}

---

POST /api/spaces/{space_id}/trackers

Create a new tracker in a space. Category is inherited from the space. Each tracker automatically gets a built-in vault for private data.

Path Parameters

Parameter	Type	Required	Description
space_id	string	Yes	Space to create the tracker in

Body Parameters (JSON)

Parameter	Type	Required	Description
name	string	Yes	Tracker name (1-50 chars)
description	string	Yes	Short summary (1-500 chars)
run_mode	string	Yes	manual or scheduled
agent_config	object	Yes	Agent configuration (see below)
shared_vault_tracker_id	string	No	Share another tracker's vault by providing its tracker ID (e.g., "trk_xxx"). If omitted or null, the tracker uses its own vault. Learn more →
vault_ttl_days	integer	No	Auto-expire vault data after N days (1-365). Null = no expiration. Applies to own vault only.
notification_config	object	No	Email/webhook notification settings (see below)
schedule	object	Conditional	Schedule configuration (see below). Required if run_mode=scheduled.

agent_config

Field	Type	Required	Description
instruction	string	Yes	HOW to analyze: methodology, data sources, and criteria (1-1000 chars). Do not include score definitions — use score_meaning.
score_meaning	string	Yes	The target to measure — what this tracker's score represents (e.g., "Market Sentiment", "Brand Visibility"). By default 10 = positive and 0 = negative; optionally clarify the axis in the value if your metric is non-obvious.
skills	string[]	Yes	List of skill IDs (e.g., ["web"], ["financial_markets", "web"])
reasoning_mode	string	No	basic (×1), advanced (×8), or super (×30). Default: basic
linked_trackers	string[]	No	Tracker IDs to use as context (max 10). Can include same-space trackers and starred public trackers.

notification_config

Field	Type	Required	Description
score_threshold	number	No	Score threshold that triggers notifications: notifications fire when the run score is at or below this value (0–100, default: 40)
email_enabled	boolean	No	Send email to user's account email (default: false)
webhook_enabled	boolean	No	Send webhook to account-level webhook endpoint (default: false)

schedule (required if run_mode=scheduled)

Field	Type	Required	Description
start_time	string	Yes	ISO 8601 datetime (UTC) for when the schedule starts
interval_minutes	integer	Yes	Execution interval in minutes (1–44640, ~31 days; e.g. daily 1440, weekly 10080)
end_time	string	No	ISO 8601 datetime (UTC) for when the schedule ends. null = run forever.

Request — basic tracker (no linked trackers)

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer qapi_..." \
  -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"
    }
  }'

Response (201 Created)

{
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "Tesla Sentiment",
  "description": "Tracks Tesla stock sentiment from news and social media",
  "run_mode": "manual",
  "schedule": null,
  "shared_vault_tracker_id": null,
  "vault_ttl_days": null,
  "agent_config": {
    "instruction": "Analyze market sentiment for Tesla (TSLA)...",
    "score_meaning": "Market Sentiment",
    "skills": ["financial_markets"],
    "reasoning_mode": "basic",
    "linked_trackers": []
  },
  "notification_config": null,
  "category": "finance",
  "visibility": "private",
  "last_run_at": null,
  "created_at": "2026-02-18T10:30:00Z",
  "updated_at": "2026-02-18T10:30:00Z"
}

Request — with linked trackers

curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/trackers \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portfolio Risk Monitor",
    "description": "Aggregates scores from sector trackers to assess overall portfolio risk",
    "run_mode": "manual",
    "agent_config": {
      "instruction": "Evaluate overall portfolio risk by synthesizing results from linked sector trackers. Consider correlations, divergences across sectors, and any conflicting scores.",
      "score_meaning": "Portfolio Risk Level",
      "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"]
    }
  }'

Response (201 Created)

{
  "tracker_id": "trk_d2e3f4a5-6b7c-48d9-e0f1-2a3b4c5d6e7f",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "Portfolio Risk Monitor",
  "description": "Aggregates scores from sector trackers to assess overall portfolio risk",
  "run_mode": "manual",
  "schedule": null,
  "shared_vault_tracker_id": null,
  "vault_ttl_days": null,
  "agent_config": {
    "instruction": "Evaluate overall portfolio risk by synthesizing results from linked sector trackers...",
    "score_meaning": "Portfolio Risk Level",
    "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"]
  },
  "notification_config": null,
  "category": "finance",
  "visibility": "private",
  "last_run_at": null,
  "created_at": "2026-03-01T14:00:00Z",
  "updated_at": "2026-03-01T14:00:00Z"
}

Linked Tracker Requirements

• Same-space trackers can be linked directly by their tracker_id.
• Public trackers must be starred (via the Console) before they can be linked.
• Each linked tracker adds to per-run cost — see pricing for rates.

tip

If you include notification_config in your request, it will appear with the provided values. When omitted, it defaults to null.

---

Trackers

AI-powered monitoring jobs that produce scored results. Learn more →

GET /api/trackers

List trackers in a space. Trackers are always scoped to a space.

Query Parameters

Parameter	Type	Required	Description
space_id	string	Yes	Filter by space
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request

curl "https://api.quantinal.ai/v1/api/trackers?space_id=spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7" \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)

{
  "data": [
    {
      "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
      "name": "Tesla Sentiment",
      "description": "Tracks Tesla stock sentiment from news and social media",
      "run_mode": "manual",
      "schedule": null,
      "agent_config": {
        "instruction": "Analyze Tesla (TSLA) considering recent news, analyst reports, and price momentum.",
        "score_meaning": "Market Sentiment",
        "skills": ["financial_markets"],
        "reasoning_mode": "basic",
        "linked_trackers": []
      },
      "notification_config": {
      "score_threshold": 20,
      "email_enabled": false,
      "webhook_enabled": false
    },
    "shared_vault_tracker_id": null,
    "vault_ttl_days": null,
    "category": "finance",
    "visibility": "private",
    "last_run_at": "2026-02-18T10:30:00Z",
    "created_at": "2026-02-18T10:30:00Z",
    "updated_at": "2026-02-18T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total_items": 1, "total_pages": 1 }
}

---

GET /api/trackers/{tracker_id}

Get full tracker configuration and status.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Request

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

Response (200 OK)

{
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "Tesla Sentiment",
  "description": "Tracks Tesla stock sentiment from news and social media",
  "run_mode": "manual",
  "schedule": null,
  "shared_vault_tracker_id": null,
  "vault_ttl_days": null,
  "agent_config": {
    "instruction": "Analyze market sentiment for Tesla (TSLA)...",
    "score_meaning": "Market Sentiment",
    "skills": ["financial_markets"],
    "reasoning_mode": "basic",
    "linked_trackers": []
  },
  "notification_config": {
    "score_threshold": 20,
    "email_enabled": false,
    "webhook_enabled": false
  },
  "category": "finance",
  "visibility": "private",
  "last_run_at": "2026-02-18T10:30:00Z",
  "created_at": "2026-02-18T10:30:00Z",
  "updated_at": "2026-02-18T10:30:00Z"
}

---

PATCH /api/trackers/{tracker_id}

Update tracker configuration. Partial updates — only send the fields you want to change.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Body Parameters (JSON — all optional)

Parameter	Type	Required	Description
name	string	No	New name (1-50 chars)
description	string	No	New description (1-500 chars)
run_mode	string	No	manual or scheduled
agent_config	object	No	New agent configuration
shared_vault_tracker_id	string	No	Set to another tracker's tracker ID (e.g., "trk_xxx") to share its vault, or omit to keep current. Set to null to revert to own vault.
schedule	object	No	New schedule config. Set null to clear.
notification_config	object	No	New notification settings

Request — rename and switch to scheduled

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Tesla Daily Sentiment", "run_mode": "scheduled", "schedule": {"start_time": "2026-02-19T09:00:00Z", "interval_minutes": 1440}}'

Request — add linked trackers

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer qapi_..." \
  -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"]
    }
  }'

Returns the full updated tracker object (same shape as GET).

note

When updating agent_config, send the complete object — all fields (instruction, score_meaning, skills, reasoning_mode, linked_trackers) are replaced as a unit.

---

DELETE /api/trackers/{tracker_id}

Permanently delete a tracker and all associated data (schedules, runs, results). Irreversible.

Returns 409 Conflict if the tracker's vault is currently shared by other trackers — those trackers must set shared_vault_tracker_id to null first.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Request

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

Response (200 OK)

{"success": true, "message": "Tracker deleted successfully", "data": null, "errors": null}

Response (409 Conflict — vault is shared)

{"detail": "Cannot delete tracker: its vault is shared by 1 other tracker(s): ['trk_xxx']. They must set shared_vault_tracker_id to null first."}

---

Tracker Runs

Trigger, list, get, and delete runs for a specific tracker.

POST /api/trackers/{tracker_id}/runs — 💎 costs quants

Trigger a manual run. Costs quants based on skills, reasoning mode, and linked trackers. Supports sync and async execution modes.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker to execute

Body Parameters (JSON — optional)

Parameter	Type	Required	Description
sync	boolean	No	Wait for completion and return full result (default: false)
context	object	No	Metadata/notes for this run

Sync Mode (sync: true)

Blocks until the run finishes and returns the full result in one response. Wall time depends on reasoning mode (roughly up to several minutes for basic, up to ~15 minutes for advanced, and up to ~40 minutes for super). The API waits long enough for the runner to complete; if the load balancer or client gives up first, you may see a timeout even though the run continues — prefer async mode (sync: false) plus polling for dashboards and mobile clients.

If the API times out waiting for the runner, you may receive 504 with error_code: RUNNER_SYNC_TIMEOUT. The run may still complete in the background. Poll GET /v1/api/trackers/{tracker_id}/runs for the latest run, or switch to async mode (sync: false) and poll by run_id.

Request

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

Response (200 OK)

{
  "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. Recent earnings beat expectations, and Cybertruck delivery numbers are tracking ahead of estimates...",
    "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
}

result.baseline_score and result.score_adjustment_factors are optional and are included when factor scoring is available. Internal scoring fields such as raw_score and quality are not returned by this API.

Async Mode (default, sync: false)

Returns immediately with run_id. Poll with GET /api/trackers/{tracker_id}/runs/{run_id} for results.

Request

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

Response (202 Accepted)

{
  "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"
}

tip

Use sync: true for quick scripts and short runs when you want a single response. Use sync: false and poll for long-running advanced / super runs, high-volume triggers, or any client with a short HTTP timeout.

---

GET /api/trackers/{tracker_id}/runs

List runs for this tracker with filtering and pagination.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter: pending, running, completed, failed
notification_status	string	No	Filter: success, failed, skipped
start_date	datetime	No	Filter runs after this date (ISO 8601)
end_date	datetime	No	Filter runs before this date (ISO 8601)
min_score	number	No	Minimum score (0-100)
max_score	number	No	Maximum score (0-100)
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request

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

Response (200 OK)

{
  "data": [
    {
      "run_id": "run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
      "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
      "status": "completed",
      "started_at": "2026-02-17T14:00:00Z",
      "completed_at": "2026-02-17T14:00:38Z",
      "quants_used": 0.02,
      "result": {
        "score": 18,
        "insight": "Significant negative sentiment detected...",
        "baseline_score": 26,
        "score_adjustment_factors": [
          { "factor": "Negative analyst revisions", "impact": -10, "probability": 0.6 }
        ]
      },
      "config_snapshot": {
        "agent_config": {
          "skills": ["financial_markets"],
          "instruction": "Analyze...",
          "score_meaning": "Market Sentiment",
          "reasoning_mode": "basic",
          "linked_trackers": []
        },
        "trigger_type": "manual",
        "sync": false
      },
      "notification_delivery": {
        "email": {
          "status": "sent",
          "recipient": "user@example.com",
          "sent_at": "2026-02-17T14:00:38Z",
          "message_id": "0100019d39b282db-abc12345-6789-0000-0000-000000000000",
          "attempts": 1
        },
        "webhook": null
      },
      "error_message": null
    }
  ],
  "pagination": { "page": 1, "page_size": 5, "total_items": 2, "total_pages": 1 }
}

---

GET /api/trackers/{tracker_id}/runs/{run_id}

Get a specific run's details and result. Use this to poll for completion after an async trigger.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
run_id	string	Yes	Run ID

Request

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

Response (200 OK)

{
  "run_id": "run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "status": "completed",
  "started_at": "2026-02-18T10:00:00Z",
  "completed_at": "2026-02-18T10:00:32Z",
  "quants_used": 0.02,
  "result": {
    "score": 72,
    "insight": "Tesla sentiment is moderately bullish. Recent earnings beat expectations...",
    "baseline_score": 66,
    "score_adjustment_factors": [
      { "factor": "Earnings momentum", "impact": 12, "probability": 0.7 },
      { "factor": "Macro uncertainty", "impact": -6, "probability": 0.4 }
    ]
  },
  "config_snapshot": {
    "agent_config": {
      "skills": ["financial_markets"],
      "instruction": "Analyze market sentiment for Tesla (TSLA)...",
      "score_meaning": "Market Sentiment",
      "reasoning_mode": "basic",
      "linked_trackers": []
    },
    "trigger_type": "manual",
    "sync": false
  },
  "notification_delivery": {
    "email": null,
    "webhook": null
  },
  "error_message": null
}

---

PATCH /api/trackers/{tracker_id}/runs/{run_id}

Add, update, or clear a human feedback comment for a run.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
run_id	string	Yes	Run ID

Body Parameters (JSON)

Parameter	Type	Required	Description
comment	string | null	Yes	Comment text (max 1000). Send null or empty string to clear

Request — add/update 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 qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"comment":"Good direction, but validate with macro data next run."}'

Request — clear 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 qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"comment":null}'

Response (200 OK)

{
  "run_id": "run_9f8e7d6c-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "status": "completed",
  "started_at": "2026-02-18T10:00:00Z",
  "completed_at": "2026-02-18T10:00:32Z",
  "quants_used": 0.02,
  "result": {
    "score": 72,
    "insight": "Tesla sentiment is moderately bullish..."
  },
  "config_snapshot": {
    "agent_config": {
      "skills": ["financial_markets"],
      "instruction": "Analyze market sentiment for Tesla (TSLA)...",
      "score_meaning": "Market Sentiment",
      "reasoning_mode": "basic",
      "linked_trackers": []
    },
    "trigger_type": "manual",
    "sync": false
  },
  "run_comment": "Good direction, but validate with macro data next run.",
  "run_comment_updated_at": "2026-04-15T10:10:00Z",
  "run_comment_updated_by": "usr_123",
  "error_message": null
}

note

Comment visibility is owner-only. Public linked tracker consumers do not receive owner comments.

---

DELETE /api/trackers/{tracker_id}/runs/{run_id}

Permanently delete a run and its result data. Irreversible.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
run_id	string	Yes	Run ID to delete

Request

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 qapi_..."

Response (200 OK)

{"success": true, "message": "Run deleted successfully", "data": null, "errors": null}

---

Tracker Vault

Every tracker has a built-in vault that stores private data (files, JSON) for the agent to use as context. Multiple trackers can share the same vault — see Vault Sharing. All vault endpoints resolve to the tracker's active vault (own or shared). Learn more →

GET /api/trackers/{tracker_id}/vault

Get metadata and storage stats for the tracker's active vault (own or shared).

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Request

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

Response (200 OK)

{
  "vault_id": "vlt_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "tracker_id": "trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "Tesla Sentiment Vault",
  "description": null,
  "total_sources": 3,
  "total_data_items": 142,
  "total_size_gb": 0.0024,
  "ttl_days": null,
  "created_at": "2026-02-18T10:30:00Z",
  "updated_at": "2026-02-18T11:12:00Z"
}

---

GET /api/trackers/{tracker_id}/vault/recent

Get the most recent data items from a tracker's vault, ordered by creation time (newest first). Useful for rolling window monitoring and trend detection.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max items to return (default: 10, max: 100)
content_types	string	No	Comma-separated: text, json
since_hours	integer	No	Only items from the last N hours

Request

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

Response (200 OK)

{
  "results": [
    {
      "data_id": "d1e2f3a4-5b6c-47d8-e9f0-1a2b3c4d5e6f",
      "source_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
      "content": "{\"ticker\": \"AAPL\", \"eps\": 1.53, \"date\": \"2025-Q4\"}",
      "content_type": "json",
      "token_count": 29,
      "created_at": "2026-02-18T09:15:00Z",
      "metadata": null,
      "source_name": "earnings-data"
    }
  ],
  "total": 1
}

---

POST /api/trackers/{tracker_id}/vault/sources

Upload a file or JSON data to the tracker's vault. Rate limit: 30 req/min. If source_name matches an existing source, data is appended.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

File Upload (multipart/form-data)

Field	Type	Required	Description
file	file	Yes	PDF, CSV, TXT, or MD
source_name	string	No	Source name (defaults to filename)

File Upload

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

JSON Upload (application/json)

Field	Type	Required	Description
source_name	string	Yes	Source name (1-200 chars)
data	object or array	Yes	Single object or array of objects (batch max: 1,000 rows, 10 MB)
description	string	No	Source description for search context

Single JSON

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"source_name": "Daily Metrics", "data": {"revenue": 50000, "date": "2026-02-18"}}'

Batch JSON (up to 1,000 rows)

curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources \
  -H "Authorization: Bearer qapi_..." \
  -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"}
    ]
  }'

Response (201 Created)

{
  "source_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
  "vault_id": "vlt_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "earnings-data",
  "description": null,
  "source_type": "JSON",
  "size_bytes": 128,
  "data_count": 2,
  "rows_processed": 2,
  "is_new_source": true,
  "cost_quants": 0.0,
  "status": "completed",
  "uploaded_at": "2026-02-18T11:00:00Z",
  "updated_at": "2026-02-18T11:00:00Z",
  "metadata": null
}

---

GET /api/trackers/{tracker_id}/vault/sources

List all sources in the tracker's vault with metadata and stats. Rate limit: 200 req/min.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request

curl https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)

{
  "data": [
    {
      "source_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
      "name": "earnings-data",
      "description": null,
      "source_type": "JSON",
      "size_bytes": 128,
      "data_count": 2,
      "status": "completed",
      "uploaded_at": "2026-02-18T11:00:00Z",
      "updated_at": "2026-02-18T11:00:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total_items": 1, "total_pages": 1 }
}

---

GET /api/trackers/{tracker_id}/vault/sources/{source_id}

Get source details including size, data count, and processing status.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
source_id	string	Yes	Source ID

Request

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

Response (200 OK)

{
  "source_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
  "name": "earnings-data",
  "description": null,
  "source_type": "JSON",
  "size_bytes": 128,
  "data_count": 2,
  "status": "completed",
  "uploaded_at": "2026-02-18T11:00:00Z",
  "updated_at": "2026-02-18T11:00:00Z"
}

---

PATCH /api/trackers/{tracker_id}/vault/sources/{source_id}

Update source name or description. Does not re-index existing data.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
source_id	string	Yes	Source ID

Body Parameters (JSON — all optional)

Parameter	Type	Required	Description
name	string	No	New name (1-200 chars)
description	string	No	New description (max 500 chars)

Request

curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/vault/sources/b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Q4 Earnings", "description": "Quarterly earnings per share data"}'

Returns the full updated source object (same shape as GET).

---

DELETE /api/trackers/{tracker_id}/vault/sources/{source_id}

Permanently delete a source and all its data entries and token indexes. Irreversible.

Path Parameters

Parameter	Type	Required	Description
tracker_id	string	Yes	Tracker ID
source_id	string	Yes	Source ID

Request

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 qapi_..."

Response (200 OK)

{"success": true, "message": "Data source deleted successfully", "data": null, "errors": null}

---

Other

Utility and discovery endpoints.

GET /api/skills

List all available skills for composing tracker behavior. Use the returned skill_id values when building agent_config.skills on a tracker. Rate limited to 30 req/min — skills are stable reference data, so cache the response on your client.

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: active, disabled (default: all)
category	string	No	Filter by category: research, finance, marketing, etc.
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)

Request

curl https://api.quantinal.ai/v1/api/skills \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)

{
  "data": [
    {
      "skill_id": "web",
      "name": "Web",
      "description": "Search the web for real-time news and current events...",
      "category": "research",
      "base_cost_quants": 0.012,
      "status": "active"
    },
    {
      "skill_id": "financial_markets",
      "name": "Financial Markets",
      "description": "Live real-time quotes for stocks and crypto...",
      "category": "finance",
      "base_cost_quants": 0.012,
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 6,
    "total_pages": 1
  }
}

Response Fields

Field	Type	Description
skill_id	string	Unique skill identifier — use this in agent_config.skills
name	string	Human-readable skill name
description	string	What the skill does
category	string	Skill category (research, finance, marketing, …)
base_cost_quants	number	Base cost in quants per tracker run
status	string	active or disabled