Endpoints

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

Spaces

Free project containers for trackers and sources. Storage and throughput limits are enforced at the account level — spaces track usage via used_gb. Learn more →

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",
      "used_gb": 2.4,
      "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 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",
  "used_gb": 2.4,
  "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. Each tracker has a role tier mirroring a neural network's layers (1=Output, 2=Hidden, 3=Input; default 1). Attach 1 to 5 sources via fs_scope_sources — selecting sources enables filesystem access. Learn more →

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)
`tier`	integer	No	Role tier: `1`=Output (default), `2`=Hidden, `3`=Input
`run_mode`	string	Yes	`manual` or `scheduled`
`agent_config`	object	Yes	Agent configuration (see below)
`fs_scope_sources`	string[]	No	Source paths to attach (1 to 5). Selecting sources enables filesystem access; omit or send an empty list for no access. There is no whole-space mode. Example: `["/financials/", "/reports/"]`
`fs_data_hints`	string	No	Free-text guidance about the sources. Only applies when sources are attached.
`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` (×6), `super` (×25), or `zen` (×55, async only). Default: `basic`
`linked_trackers`	string[]	No	Your own tracker IDs to use as context (max 10, same account).

notification_config

Notifications use independent lower/upper bounds so you can alert on a drop, a spike, or both.

Field	Type	Required	Description
`notify_below`	boolean	No	Notify when score is at or below `lower_threshold` (default: `false`)
`lower_threshold`	integer	No	Lower bound (0–100, default: `40`); alert fires when score ≤ this value
`notify_above`	boolean	No	Notify when score is at or above `upper_threshold` (default: `false`)
`upper_threshold`	integer	No	Upper bound (0–100, default: `80`); alert fires when score ≥ this value
`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`)
`score_threshold`	number	No	Legacy single threshold (0–100); used only when `notify_below`/`notify_above` are both absent
`threshold_direction`	string	No	Legacy direction for `score_threshold`: `"below"` or `"above"`

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,
  "use_space_filesystem": false,
  "fs_scope_sources": null,
  "fs_data_hints": 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,
  "tier": 1,
  "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,
  "use_space_filesystem": false,
  "fs_scope_sources": null,
  "fs_data_hints": 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,
  "tier": 1,
  "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 (must exist in the target space).
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.

Sources

Sources and files are scoped to a space. A source is a named path (e.g. /financials/) that groups uploaded files. Manage sources with /api/spaces/{space_id}/sources; upload and manage files with /api/spaces/{space_id}/files. Each file carries a source field (the path it belongs to). List files in a source with GET .../files?source=/financials/. Files can be moved between sources, so source is mutable metadata rather than part of the URL path. Attach up to five sources to a tracker via fs_scope_sources. Learn more →

Source paths

Each source is identified by a path like /financials/ (the key field). Use it as the source when uploading files and in a tracker's fs_scope_sources.

use_space_filesystem is read-only

Tracker responses include a use_space_filesystem boolean, but it is derived from fs_scope_sources (true when a tracker has sources) — you don't set it on create/update. To enable access, attach sources; to disable, clear them.

Managing sources

GET /api/spaces/{space_id}/sources

List all sources in a space, including file counts and total size. Auto-discovered sources (files uploaded before the source was named) and the implicit General source (path /) may appear in the list.

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

Response (200 OK)
{
  "items": [
    {
      "key": "/financials/",
      "name": "Financials",
      "description": "Quarterly reports and earnings",
      "metadata": null,
      "created_at": "2026-02-10T08:00:00Z",
      "updated_at": null,
      "file_count": 3,
      "total_size_bytes": 245760
    }
  ],
  "total": 1
}

POST /api/spaces/{space_id}/sources

Create a new source. A unique path (key) is generated from the name unless you pass an explicit key (for naming an auto-discovered source).

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID

Body Parameters (JSON)

Parameter	Type	Required	Description
`name`	string	Yes	Display name (1–50 chars)
`description`	string	No	Description (max 500 chars)
`metadata`	object	No	Optional metadata
`key`	string	No	Explicit source path (e.g. `/financials/`)

Request
curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/sources \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Financials", "description": "Quarterly reports"}'

Response (201 Created)
{
  "key": "/financials/",
  "name": "Financials",
  "description": "Quarterly reports",
  "metadata": null,
  "created_at": "2026-02-18T10:00:00Z",
  "updated_at": null,
  "file_count": 0,
  "total_size_bytes": 0
}

PATCH /api/spaces/{space_id}/sources

Update a source's name, description, or metadata. The source path (key) is immutable.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID

Query Parameters

Parameter	Type	Required	Description
`key`	string	Yes	Source path, URL-encoded (e.g. `%2Ffinancials%2F`)

Body Parameters (JSON — all optional)

Parameter	Type	Required	Description
`name`	string	No	New display name
`description`	string	No	New description
`metadata`	object	No	New metadata

Request
curl -X PATCH "https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/sources?key=%2Ffinancials%2F" \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Q4 earnings and filings"}'

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

DELETE /api/spaces/{space_id}/sources

Delete a source and all files within it. The General source (path /) cannot be deleted.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID

Query Parameters

Parameter	Type	Required	Description
`key`	string	Yes	Source path, URL-encoded

Request
curl -X DELETE "https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/sources?key=%2Ffinancials%2F" \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{"success": true, "message": "Source deleted (3 files removed)", "data": null, "errors": null}

Files

Files are the uploaded data (PDF, CSV, TXT, MD, or JSON) that live inside a source. Each file is scoped to its space and belongs to a source path.

POST /api/spaces/{space_id}/files

Upload a file or JSON data into a source. Rate limit: 30 req/min. If file_name matches an existing file under the same source, data is appended.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID

File Upload (`multipart/form-data`)

Field	Type	Required	Description
`file`	file	Yes	PDF, CSV, TXT, or MD
`file_name`	string	No	File name (defaults to filename)
`source`	string	No	Source path (e.g. `/financials/`)

File Upload
curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files \
  -H "Authorization: Bearer qapi_..." \
  -F "file=@report.pdf" \
  -F "file_name=Q4 Report" \
  -F "source=/financials/"

JSON Upload (`application/json`)

Field	Type	Required	Description
`file_name`	string	Yes	File 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	Description for search context
`source`	string	No	Source path (e.g. `/financials/`)

Single JSON
curl -X POST https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{"file_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/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files \
  -H "Authorization: Bearer qapi_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "earnings-data",
    "source": "/financials/",
    "data": [
      {"ticker": "AAPL", "eps": 1.53, "date": "2025-Q4"},
      {"ticker": "MSFT", "eps": 3.23, "date": "2025-Q4"}
    ]
  }'

Response (201 Created)
{
  "file_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
  "space_id": "spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7",
  "name": "earnings-data",
  "description": null,
  "source": "/financials/",
  "file_type": "JSON",
  "size_bytes": 128,
  "data_count": 2,
  "rows_processed": 2,
  "is_new_file": 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/spaces/{space_id}/files

List all uploaded files in the space with metadata and stats. Rate limit: 200 req/min.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Items per page (default: 20, max: 1000)
`source`	string	No	Only files under this source path

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

Response (200 OK)
{
  "data": [
    {
      "file_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
      "name": "earnings-data",
      "description": null,
      "source": "/financials/",
      "file_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/spaces/{space_id}/files/{file_id}

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

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID
`file_id`	string	Yes	File ID

Request
curl https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files/b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer qapi_..."

Response (200 OK)
{
  "file_id": "b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e",
  "name": "earnings-data",
  "description": null,
  "source": "/financials/",
  "file_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/spaces/{space_id}/files/{file_id}

Update a file's name, description, or source. Does not re-index existing data.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID
`file_id`	string	Yes	File 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)
`source`	string	No	New source path

Request
curl -X PATCH https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files/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 file object (same shape as GET).

DELETE /api/spaces/{space_id}/files/{file_id}

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

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space ID
`file_id`	string	Yes	File ID

Request
curl -X DELETE https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/files/b4c5d6e7-8f9a-4b0c-1d2e-3f4a5b6c7d8e \
  -H "Authorization: Bearer qapi_..."

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

GET /api/spaces/{space_id}/filesystem/recent

Get the most recent data items across the space, ordered by creation time (newest first). Useful for rolling window monitoring and trend detection.

Path Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Space 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`
`sources`	string	No	Comma-separated source paths to restrict results
`since_hours`	integer	No	Only items from the last N hours

Request
curl "https://api.quantinal.ai/v1/api/spaces/spc_f30e60c1-75fd-47f7-967e-29afc19a3ea7/filesystem/recent?limit=5&since_hours=24" \
  -H "Authorization: Bearer qapi_..."

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

Trackers

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

GET /api/trackers

List the authenticated user's trackers in a space. API tokens must pass space_id.

Query Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes (API tokens)	Scope to a single space owned by the caller. Returns 403 if the space is not yours.
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Items per page (default: 20, max: 100)

Results are sorted by updated_at descending before pagination.

Request — space-scoped (API token)
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": null,
      "threshold_direction": null,
      "notify_below": true,
      "lower_threshold": 40,
      "notify_above": true,
      "upper_threshold": 80,
      "email_enabled": false,
      "webhook_enabled": false
    },
    "use_space_filesystem": false,
    "fs_scope_sources": null,
    "fs_data_hints": null,
    "tier": 1,
    "last_run_at": "2026-02-18T10:30:00Z",
    "created_at": "2026-02-18T10:30:00Z",
    "updated_at": "2026-02-18T10:30:00Z",
    "latest_score": 72,
    "previous_score": 68,
    "last_score_change": 4,
    "abs_score_change": 4
    }
  ],
  "pagination": { "page": 1, "page_size": 20, "total_items": 1, "total_pages": 1 }
}

Each item also includes latest_score, previous_score, last_score_change, and abs_score_change derived from the tracker's most recent runs (all null before the first completed run).

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,
  "use_space_filesystem": false,
  "fs_scope_sources": null,
  "fs_data_hints": 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": null,
    "threshold_direction": null,
    "notify_below": true,
    "lower_threshold": 40,
    "notify_above": true,
    "upper_threshold": 80,
    "email_enabled": false,
    "webhook_enabled": false
  },
  "tier": 1,
  "last_run_at": "2026-02-18T10:30:00Z",
  "created_at": "2026-02-18T10:30:00Z",
  "updated_at": "2026-02-18T10:30:00Z",
  "latest_score": 72,
  "previous_score": 68,
  "last_score_change": 4,
  "abs_score_change": 4
}

The tracker payload also carries convenience score fields derived from its runs: latest_score and previous_score (most recent two completed run scores, or null), last_score_change (signed delta), and abs_score_change (absolute delta). These let you read current state without fetching the run history.

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)
`tier`	integer	No	New role tier: `1`=Output, `2`=Hidden, `3`=Input
`run_mode`	string	No	`manual` or `scheduled`
`agent_config`	object	No	New agent configuration
`fs_scope_sources`	string[]	No	Source paths (1 to 5). Selecting sources enables filesystem access; send an empty list to disable it.
`fs_data_hints`	string	No	Free-text guidance about the sources. `null` = none.
`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. Sources in the space are not affected.

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}

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, up to ~50 minutes for super). zen requires async mode (sync: false) — sync requests return 400. Prefer async mode plus polling for long-running runs and any client with a short HTTP timeout.

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...",
    "score_adjustment_factors": [
      { "factor": "Earnings momentum", "impact": 12, "probability": 0.7 },
      { "factor": "Macro uncertainty", "impact": -6, "probability": 0.4 }
    ]
  },
  "error_message": null
}

result.score_adjustment_factors is optional and is included when factor scoring is available. Internal fields such as raw_score, quality, baseline_score, and reasoning-engine inference_metadata 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...",
        "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...",
    "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
  },
  "run_comment": null,
  "run_comment_updated_at": null,
  "run_comment_updated_by": 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 on run payloads.

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}

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`

Spaces​

Sources​

Managing sources​

Files​

File Upload (multipart/form-data)​

JSON Upload (application/json)​

Trackers​

Tracker Runs​

Sync Mode (sync: true)​

Async Mode (default, sync: false)​

Other​

Spaces

Sources

Managing sources

Files

File Upload (`multipart/form-data`)

JSON Upload (`application/json`)

Trackers

Tracker Runs

Sync Mode (`sync: true`)

Async Mode (default, `sync: false`)

Other