Reading Data

This page covers how to read Runnit data: projects, users, tasks, clients, briefs, jobs, schedules, costs, and more.

Prefer plain HTTP?

The same data is also available over the public REST API at /api/v1, authenticated with the same per-user API keys. Use the REST API for scripts and integrations; use the MCP read tools below when an AI agent is doing the work.

How it works

Connect over the MCP server with a user-scoped token, then call the read tools. Every tool is:

• Organisation-scoped to the connected user: results reflect that user’s permissions. A forbidden or empty result is expected when the user lacks access; it is not an error to retry.
• Read-only and returns safe fields only: never passwords, tokens, embeddings, or rate-card internals.

Authentication follows the two modes in MCP Tools: bearer-header clients omit apiKey; payload-based workflows pass the user-scoped token as apiKey on every call.

{
  "tool": "list_projects",
  "arguments": { "status": "active", "limit": 50 }
}

Projects

Tool	Purpose	Key arguments
list_projects	List projects in the organisation.	status, includeArchived, limit (default 100, max 500)
get_project	Get one project by id.	id
list_project_members	Members assigned to a project.	projectId, limit (default 200, max 500)
list_milestones	Project milestones.	projectId, limit (default 200, max 1000)
list_project_history	A project’s activity/changelog feed.	projectId, taskId, categories[], eventTypes[], limit (default 100, max 200)

Master Projects

Tool	Purpose	Key arguments
list_master_projects	List master projects.	status, clientOrganizationId, limit (default 100, max 500)
get_master_project	Get one master project by id.	id

Tasks

Tool	Purpose	Key arguments
list_tasks	List project tasks.	projectId, assigneeId, status, openOnly, completedSince, dueOn, limit (default 200, max 1000)
get_task	Get one task by id.	id
list_task_counts	Per-project task totals in one call (avoids per-project loops).	projectIds[]
list_task_comments	Comments for a task, or every comment across a project.	one of taskId / projectId, limit (default 100, max 500)

Users & Clients

Tool	Purpose	Key arguments
list_users	Organisation members (team).	role, isActive, limit (default 200, max 1000)
get_user	Get one user by id.	userId
list_clients	Client organisations you have a relationship with.	relationshipStatus, limit (default 200, max 1000)
get_client	Get one client organisation.	clientOrganizationId

Briefs & Jobs

Tool	Purpose	Key arguments
list_briefs	Brief builder sessions.	isComplete, isArchived (default false), clientOrganizationId, masterProjectId, limit (default 100, max 500)
get_brief	Get one brief (includes its current brief markdown).	id
list_jobs	Background/agent jobs.	status, jobType, userId, projectId, since, until, limit (default 100, max 500)

Schedule, Time & Cost

Tool	Purpose	Key arguments
list_schedule_entries	Planned task time slots (calendar/Gantt/utilisation).	taskId, userId, projectId, since, until, limit (default 500, max 5000)
list_time_entries	Logged time: the source for hours completed/timesheets.	projectId, taskId, userId, since, until, billableOnly, status, limit (default 500, max 5000)
get_project_cost	Accurate cost rollup for one project (totals + by user/role/month).	projectId, since, until
list_project_costs	Per-project cost summary across the organisation.	since, until, clientOrganizationId, status, limit (default 200, max 1000)

Agents & Assets

Tool	Purpose	Key arguments
list_agents	AI agent definitions available to the organisation.	isActive, interactionMode, limit (default 200, max 500)
get_agent	Get one agent definition by id.	id
list_files / read_file / search_assets	Read files and assets. See MCP Tools.	varies

REST alternatives

If you’d rather call HTTP endpoints directly, the public REST API at /api/v1 covers projects, tasks, master projects, organisations, clients, users, reports, schedules, collections, assets, permissions, and search, authenticated with the same rnk_ API keys that work here.

A few specialised capabilities also have their own documented endpoints:

• Agent Schedule API: read schedules and business days.
• File API: read and write files/assets.
• Image Generation API and Video Generation API: generate media.