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.

For the current user’s actionable work, call call_public_api with GET /tasks/my. Draft-project assignments stay out of that list and its totals. list_tasks and list_schedule_entries include planning work so you can review it before activation. See Tasks API and Scheduling API.

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. Pass jobNumber to find one project by its exact job number (case-insensitive, includes archived projects), or search to match part of a project name or job number.	status, jobNumber, search, 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)
list_project_comments	All discussion on a project, newest first: the project’s own chat thread plus the comments on its tasks. Each row has source (project or task), body, authorType, user, createdAt, and task details on task rows.	projectId, scope (all, project, tasks), limit (default 100, max 500)

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 across the organisation in one call. Assignment, estimate, and planned dates can be null. Use scheduled: false for backlog work without a complete planned window, overdue: true for open tasks past their due date (each task then reports daysOverdue), compact: true for a short record per task, and groupBy: "assignee" to get one group per person with taskCount and overdueCount. Every task includes assigneeName.	projectId, assigneeId, status, scheduled, openOnly, overdue, completedSince, dueOn, compact, groupBy, 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. Comments are the entries in each task’s chat thread. For a project’s whole discussion, including its own project-level chat, use list_project_comments.	one of taskId / projectId, limit (default 100, max 500)
list_table_columns	The custom task-table columns a project sees, including columns inherited from its client or the organisation. Task values for these columns sit in task metadata under tableValues, keyed by column key. Also reports defaultColumns and defaultColumnsSource: the default visible column set configured for the project’s table (from its kanban board, else the organisation setting), or null.	projectId

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. With no status filter (or active), the first entry is the virtual internal client (id: "internal", isInternal: true): your own organisation, used for internal work.	relationshipStatus, limit (default 200, max 1000)
get_client	Get one client organisation. Your own organisation’s id resolves to the internal client (isInternal: true).	clientOrganizationId
list_client_team	The client’s default staffing pool for AI and initial planning. When hasRestrictions is true, start with the returned members. An existing project’s owner and active project members remain eligible for that project, including project-only additions.	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)
get_job	Get one job by id: status, progress, and, for planning jobs, the projectId once the draft project exists. Use it to poll a job started by start_brief_planning or create_from_capture. The job’s error detail is returned only to the person who started it.	id

Schedule, Time & Cost

Tool	Purpose	Key arguments
list_schedule_entries	Planned task time slots, including tentative and held capacity. Each row includes projectStatus and bookingState. Personal calendars include only confirmed entries outside draft. Returns exact totalCount, totalMinutes, totalHours and a truncated flag for the whole filtered set, plus server-side groups when you pass groupBy.	taskId, userId, projectId, since, until, limit (default 500, max 5000), groupBy (day, week, month, user, project)
check_team_availability	Real free capacity for users over a date range, evaluated against their existing bookings across all projects (8 working hours per weekday). Organisation closure dates and fully blocked days are excluded from free capacity, partially blocked days subtract their blocked hours, and each user’s blocked dates in the window are reported: fully blocked days as blockedDates and partial days as partialBlockedDates ({date, hoursUnavailable, remainingHours}). Reports availability status, scheduled hours, free hours vs requiredHours, and conflicts per user.	startDate, endDate (both YYYY-MM-DD, required), requiredHours, userIds, projectId (evaluates that project’s team; omit both for the whole organisation)
get_blocked_dates	Date ranges users have blocked out as unavailable (leave, appointments). Each row carries hoursUnavailable: null means the whole day is blocked and the scheduler never books work on it; a number means only that many hours per day are unavailable. Defaults to the requesting user; reading other users’ blocks requires schedule view access. Free-text reasons are returned only for the requesting user’s own blocks unless the caller has schedule management access.	userIds[], startDate, endDate (window, both YYYY-MM-DD, optional)
get_work_pattern	How many hours a person works on each weekday, plus the history of earlier patterns and the organisation’s default day. Returns null when nobody has set a pattern, which means every weekday uses the organisation default. Defaults to the requesting user; reading another person’s requires schedule view access.	userId (optional)
list_time_entries	Logged time: the source for hours completed/timesheets. Returns exact totalCount, totalMinutes, totalHours and a truncated flag for the whole filtered set, plus server-side groups when you pass groupBy.	projectId, taskId, userId, since, until, billableOnly, status, limit (default 500, max 5000), groupBy (day, week, month, user, project, task)
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. totals, totalCount, and truncated cover every matching project even when the rows array is paged.	since, until, clientOrganizationId, status, limit (default 200, max 1000)

Note

The rows arrays on list_schedule_entries, list_time_entries, and list_project_costs are paged by limit, but their totals are not: totalCount and the hour and cost totals always cover every entry that matches your filters, and truncated: true tells you the rows array is incomplete. For sums and per-period rollups (for example monthly scheduled demand), don’t add up rows yourself. Read the totals, or pass groupBy and read groups: each group has key, count, totalMinutes, and totalHours, with day, week, and month keys bucketed in your organisation’s time zone.

Assets

Tool	Purpose	Key arguments
list_files / read_file / read_document / search_assets	List or search files, read a known file, or extract document text. Direct private-file reads need the connected user’s source access; listings and search omit private files. See MCP Tools.	varies
get_indexing_health	Whether the files the caller can search are actually indexed: counts by status and index quality (content vs metadata only), scanned documents awaiting OCR, and the last background sweep. Organisation-wide, or one collection.	collectionId (optional)

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, closure and blocked dates, 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.