Endpoints

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

Spaces

Project containers for trackers and results. Learn more →

Read-Only via API

API tokens can list and get spaces, and create trackers inside them. 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	Description
`page`	integer	Page number (default: 1)
`page_size`	integer	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_abc123",
      "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": 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	Description
`space_id`	string	Required. Space ID

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

Response (200 OK)
{
  "space_id": "spc_abc123",
  "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"
}

Trackers

AI-powered monitoring jobs that produce signals. Learn more →

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	Description
`space_id`	string	Required. Space to create the tracker in

Body Parameters (JSON)

Parameter	Type	Description
`name`	string	Required. Tracker name (1-50 chars)
`description`	string	Required. Short summary (1-500 chars)
`run_mode`	string	Required. `manual` or `scheduled`
`agent_config`	object	Required. Agent configuration (see below)
`vault_ttl_days`	integer	Auto-expire vault data after N days (1-365). Null = no expiration.
`notification_config`	object	Optional email/webhook notification settings (see below)
`schedule`	object	Schedule configuration (see below). Required if `run_mode=scheduled`.

agent_config

Field	Type	Description
`instruction`	string	Required. HOW to analyze: methodology, data sources, and criteria (1-1000 chars). Do not include score definitions — use `score_meaning`.
`score_meaning`	string	Required. 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[]	Required. List of skill IDs (e.g., `["web_research"]`, `["stock_research", "web_research"]`)
`reasoning_mode`	string	`basic` (×1), `advanced` (×8), or `super` (×30). Default: `basic`
`linked_trackers`	string[]	Tracker IDs to use as context (max 5)

notification_config

Field	Type	Description
`signal_level`	string	Signal level that triggers notifications: `Any`, `Poor`, `Negative`, `Neutral`, `Positive`, or `Excellent` (default: `Poor`)
`email_enabled`	boolean	Send email to user's account email (default: `false`)
`webhook_enabled`	boolean	Send webhook to account-level webhook endpoint (default: `false`)

schedule (required if run_mode=scheduled)

Field	Type	Description
`start_time`	string	Required. ISO 8601 datetime (UTC) for when the schedule starts
`interval_minutes`	integer	Required. Execution interval in minutes (1–1440)
`end_time`	string	ISO 8601 datetime (UTC) for when the schedule ends. `null` = run forever.

Request
curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_abc123/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": ["stock_research"],
      "reasoning_mode": "basic"
    }
  }'

Response (201 Created)
{
  "tracker_id": "trk_xyz789",
  "space_id": "spc_abc123",
  "name": "Tesla Sentiment",
  "description": "Tracks Tesla stock sentiment from news and social media",
  "run_mode": "manual",
  "schedule": null,
  "vault_ttl_days": null,
  "agent_config": {
    "instruction": "Analyze market sentiment for Tesla (TSLA)...",
    "score_meaning": "Market Sentiment",
    "skills": ["stock_research"],
    "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"
}

tip

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

GET /api/trackers

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

Query Parameters

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

Request
curl "https://api.quantinal.ai/v1/api/trackers?space_id=spc_abc123" \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "data": [
    {
      "tracker_id": "trk_xyz789",
      "space_id": "spc_abc123",
      "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": ["stock_research"],
        "reasoning_mode": "basic",
        "linked_trackers": []
      },
      "notification_config": {
        "signal_level": "Poor",
        "email_enabled": false,
        "webhook_enabled": false
      },
      "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	Description
`tracker_id`	string	Required. Tracker ID

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

Response (200 OK)
{
  "tracker_id": "trk_xyz789",
  "space_id": "spc_abc123",
  "name": "Tesla Sentiment",
  "description": "Tracks Tesla stock sentiment from news and social media",
  "run_mode": "manual",
  "schedule": null,
  "vault_ttl_days": null,
  "agent_config": {
    "instruction": "Analyze market sentiment for Tesla (TSLA)...",
    "score_meaning": "Market Sentiment",
    "skills": ["stock_research"],
    "reasoning_mode": "basic",
    "linked_trackers": []
  },
  "notification_config": {
    "signal_level": "Poor",
    "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	Description
`tracker_id`	string	Required. Tracker ID

Body Parameters (JSON — all optional)

Parameter	Type	Description
`name`	string	New name (1-50 chars)
`description`	string	New description (1-500 chars)
`run_mode`	string	`manual` or `scheduled`
`agent_config`	object	New agent configuration
`schedule`	object	New schedule config. Set `null` to clear.
`notification_config`	object	New notification settings

Request
curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_xyz789 \
  -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}}'

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

DELETE /api/trackers/{tracker_id}

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

Path Parameters

Parameter	Type	Description
`tracker_id`	string	Required. Tracker ID

Request
curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_xyz789 \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{"success": true, "message": "Tracker deleted successfully", "data": null, "errors": null}

Tracker Runs

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

POST /api/trackers/{tracker_id}/runs

Trigger a manual run. Supports sync and async execution modes.

Path Parameters

Parameter	Type	Description
`tracker_id`	string	Required. Tracker to execute

Body Parameters (JSON — optional)

Parameter	Type	Description
`sync`	boolean	Wait for completion and return full result (default: `false`)
`context`	object	Optional metadata/notes for this run

Sync Mode (`sync: true`)

Blocks until completion. Returns full result in a single request.

Request
curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_xyz789/runs \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"sync": true}'

Response (200 OK)
{
  "run_id": "run_abc123",
  "tracker_id": "trk_xyz789",
  "status": "completed",
  "started_at": "2026-02-18T10:00:00Z",
  "completed_at": "2026-02-18T10:00:45Z",
  "execution_time_seconds": 45.2,
  "result": {
    "score": 7,
    "signal": "Positive",
    "analysis": "Tesla sentiment is moderately bullish. Recent earnings beat expectations, and Cybertruck delivery numbers are tracking ahead of estimates..."
  },
  "error_message": null
}

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_xyz789/runs \
  -H "Authorization: Bearer qapi_..."

Response (202 Accepted)
{
  "run_id": "run_abc123",
  "tracker_id": "trk_xyz789",
  "status": "pending",
  "created_at": "2026-02-18T10:00:00Z"
}

tip

Use sync: true for simple integrations — no polling needed. Use async mode for batch operations or long-running super reasoning.

GET /api/trackers/{tracker_id}/runs

List runs for this tracker with filtering and pagination.

Path Parameters

Parameter	Type	Description
`tracker_id`	string	Required. Tracker ID

Query Parameters

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

Request
curl "https://api.quantinal.ai/v1/api/trackers/trk_xyz789/runs?status=completed&signal=Poor&page_size=5" \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "data": [
    {
      "run_id": "run_abc123",
      "tracker_id": "trk_xyz789",
      "space_id": "spc_abc123",
      "status": "completed",
      "started_at": "2026-02-17T14:00:00Z",
      "completed_at": "2026-02-17T14:00:38Z",
      "quants_used": 0.02,
      "result": {
        "score": 2,
        "signal": "Poor",
        "analysis": "Significant negative sentiment detected..."
      },
      "config_snapshot": {
        "agent_config": {
          "skills": ["stock_research"],
          "instruction": "Analyze...",
          "score_meaning": "Market Sentiment",
          "reasoning_mode": "basic",
          "linked_trackers": []
        },
        "trigger_type": "manual",
        "sync": false
      },
      "notification_delivery": {
        "email": null,
        "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	Description
`tracker_id`	string	Required. Tracker ID
`run_id`	string	Required. Run ID

Request
curl https://api.quantinal.ai/v1/api/trackers/trk_xyz789/runs/run_abc123 \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "run_id": "run_abc123",
  "tracker_id": "trk_xyz789",
  "space_id": "spc_abc123",
  "status": "completed",
  "started_at": "2026-02-18T10:00:00Z",
  "completed_at": "2026-02-18T10:00:32Z",
  "quants_used": 0.02,
  "result": {
    "score": 7,
    "signal": "Positive",
    "analysis": "Tesla sentiment is moderately bullish. Recent earnings beat expectations..."
  },
  "config_snapshot": {
    "agent_config": {
      "skills": ["stock_research"],
      "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
}

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

Permanently delete a run and its result data. Irreversible.

Path Parameters

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

Request
curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_xyz789/runs/run_abc123 \
  -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 during analysis. Learn more →

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	Description
`tracker_id`	string	Required. Tracker ID

Query Parameters

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

Request
curl "https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/recent?limit=5&since_hours=24" \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "target": "vault",
  "mode": "retrieve",
  "filters_applied": {
    "mode": "retrieve",
    "keywords": null,
    "content_types": null,
    "since": null,
    "until": null,
    "limit": 5,
    "group_by": null,
    "order_by": "created_at",
    "order": "desc"
  },
  "results": [
    {
      "data_id": "d1e2f3a4-...",
      "source_id": "src_jkl345",
      "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 — Free

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	Description
`tracker_id`	string	Required. Tracker ID

File Upload (`multipart/form-data`)

Field	Type	Description
`file`	file	Required. PDF, CSV, TXT, MD, JPG, JPEG, or PNG
`source_name`	string	Source name (defaults to filename)
`description`	string	Description for images (10-500 chars)

File Upload
curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/sources \
  -H "Authorization: Bearer qapi_..." \
  -F "file=@report.pdf" \
  -F "source_name=Q4 Report"

JSON Upload (`application/json`)

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

Single JSON
curl -X POST https://api.quantinal.ai/v1/api/trackers/trk_xyz789/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_xyz789/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": "src_jkl345",
  "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	Description
`tracker_id`	string	Required. Tracker ID

Query Parameters

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

Request
curl https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/sources \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "data": [
    {
      "source_id": "src_jkl345",
      "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	Description
`tracker_id`	string	Required. Tracker ID
`source_id`	string	Required. Source ID

Request
curl https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/sources/src_jkl345 \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "source_id": "src_jkl345",
  "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	Description
`tracker_id`	string	Required. Tracker ID
`source_id`	string	Required. Source ID

Body Parameters (JSON — all optional)

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

Request
curl -X PATCH https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/sources/src_jkl345 \
  -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	Description
`tracker_id`	string	Required. Tracker ID
`source_id`	string	Required. Source ID

Request
curl -X DELETE https://api.quantinal.ai/v1/api/trackers/trk_xyz789/vault/sources/src_jkl345 \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{"success": true, "message": "Data source deleted successfully", "data": null, "errors": null}

Spaces​

Trackers​

Tracker Runs​

Sync Mode (sync: true)​

Async Mode (default, sync: false)​

Tracker Vault​

File Upload (multipart/form-data)​

JSON Upload (application/json)​

Spaces

Trackers

Tracker Runs

Sync Mode (`sync: true`)

Async Mode (default, `sync: false`)

Tracker Vault

File Upload (`multipart/form-data`)

JSON Upload (`application/json`)