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

For the roles shown beside project tasks, use call_public_api with GET /projects/<project-id>/details. The response includes selected project role names and staff role titles for people assigned to tasks. A read does not add project membership or change saved rates. See project details for the fields and the project-role update request. This generic bridge remains unavailable to client-scoped sessions.

For a client-scoped session, list_projects and get_project only read projects for the selected active client. An Internal session only reads projects without a client. Search, job-number lookup, counts and limits use the same boundary. Membership in another project does not widen it. An out-of-scope detail returns project: null; an inactive or removed client relationship refuses the call.

The same boundary applies to list_tasks, get_task, list_task_counts, list_milestones, list_project_members, list_project_contributors, list_client_contributors, list_task_comments, list_project_comments, list_project_history, list_schedule_entries, list_time_entries, get_project_cost, list_project_costs and get_project_assets. Counts, time groups and cost totals include only matching projects before limits are applied. A known task or cost detail outside the scope returns null; lists are empty. Project files stay within the selected client even when your agency owns the file. Cost and file reads still require their usual permissions.

A project moved to another client stops appearing on later reads with the same connection. Supplying another client or organisation in tool arguments cannot expand the connection’s scope. Unscoped user-generated connections retain their ordinary access and can use the public API bridge.

list_projects uses project access and active organisation membership. Freelancers can use it without permission to browse assets. Client staffing lists and explicit project membership determine which projects appear; budget figures still require financial visibility. Staffing and permission changes apply to later calls with the same token.

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)

Project record summaries follow financial permissions. If a form contains a budget mapping that the connected user cannot read, its completeness is null and completenessFinanciallyRedacted is true. Treat the status as unavailable. See the record response contract.

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. Full records also include budgetLineId (UUID or null when unmapped); compact records omit it.	projectId, assigneeId, status, scheduled, openOnly, overdue, completedSince, dueOn, compact, groupBy, limit (default 200, max 1000)
get_task	Get one task by id, including nullable budgetLineId without budget amounts.	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. Private-file reads, listings and search follow the connected user’s current source access. Expense receipts also require the claim’s permissions. 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

For invoice reads, check kind before treating amountDue as debt. Credit notes carry document amounts, return zero daysOverdue in invoice lists and are never eligible for payment. get_payment_status returns nothing_due for them. See Invoices and credit notes.

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.

For SVG files, read_file and read_file_by_job include isBinary: true means base64 content, false means raw XML. fileSize counts decoded bytes. See SVG file content for downloads and reuse.

get_profitability honours project/client financial grants when you name the subject. It returns the same permitted metric cells as the public metrics API, including cost-only amounts. Client-bound sessions stay within their client; job-bound sessions cannot use this report. See scoped profitability for the result and validation contract.

Supplier-uploaded invoice originals and proposals follow current cost access to all linked purchase records, or organisation cost access when unattached. Linked acceptance needs readable source costs. Named file readers, discovery and the public API bridge preserve these restrictions. See Supplier invoice originals and Supplier upload cost scope.

Supplier-payment recording and reversal keep action permission separate from amount visibility. Response totals need all contributing bill cost scopes; recording also checks selected bills that receive no allocation. Remainders need organisation cost access. Authorised writes can succeed with payment identity and hidden amounts. See supplier payment visibility.

Inclusive credit lines returned by get_invoice or call_public_api keep the original line’s remaining net and tax allocation. The selected amount still includes tax. Partial credits can split net and tax differently from a fresh calculation; read the returned figures. Allocation amounts follow price access. See credit-note entry.

Named record tools accept your generated connection. Client-scoped record reads remain within the selected active client; Internal scope selects projects without a client. Form definitions and record changes require an unscoped connection. See project record tools.