Beebole GraphQL API Queries: Time Records, People, Projects

Beebole queries are the read operations of the Beebole GraphQL API. They return data from your account — your organization, people, projects, tasks, tags, time records, expenses, billing and cost rates, timesheet approvals, and custom fields — without modifying anything. Every query is sent as a POST request to https://app.beebole.com/graphql with your API key in the apikey HTTP header.

Queries never change data. To create, update, archive, or delete records, use Mutations instead. For authentication setup, see the API introduction.

Field names follow GraphQL conventions exactly as defined in the schema. Every entity exposes its identifier as id (not _id), and the organization-level query is spelled currentOrganisation (British spelling, as in the schema).

Organization

Read account-level data with currentOrganisation and getAuditTrails.

Query	Arguments	Returns
`currentOrganisation`	none	The organization linked to the authenticated API key
`getAuditTrails`	`startTime`, `fromPersonId`, `affectedPersonId`, `operations`, `argumentMatch`, `responseMatch`	Audit trail entries for the organization

query {
  currentOrganisation {
    id
    name
    locked
  }
}

getAuditTrails returns the changes recorded in the account’s audit trail. It works only for administrators, on plans that include the audit trail (not the Free plan). With no startTime, it covers the last seven days; a startTime returns the seven days that follow it. fromPersonId keeps the changes one person made, and affectedPersonId keeps the changes made to one person’s time entries, whoever made them.

query {
  getAuditTrails(operations: ["addTimeRecord", "deleteTimeRecords"]) {
    operationName
    timestamp
    person {
      id
      name
    }
    arguments {
      name
      value
    }
  }
}

People

Read team members with currentPerson, getPerson, getPersons, countPersons, and filterPersonIds. getPotentialProjectOwners lists the people who have access to a project.

Query	Arguments	Returns
`currentPerson`	none	The person linked to the API key
`getPerson`	`id`	A single person
`getPersons`	`filter`, `archived`	A list of people
`countPersons`	`filter`, `archived`	The number of matching people
`filterPersonIds`	`filter`, `archived`	Only the IDs of matching people
`getPotentialProjectOwners`	`projectId`	The people who have access to the project, as its Who has access? panel sets it

query {
  getPersons {
    id
    name
    email
    archived
  }
}

query {
  getPerson(id: "64a1b2c3d4e5f6a7b8c9d0e1") {
    id
    name
    email
    role {
      id
      name
    }
  }
}

By default getPersons returns only active people. Pass archived: true to include archived ones.

query {
  getPersons(archived: true) {
    id
    name
    archived
  }
}

List the people who have access to a project

BeebolePersonFilter has no project field, so read a project’s members with getPotentialProjectOwners. It resolves the project’s Who has access? panel: when the project is restricted, it returns the people added individually plus the people carrying one of the tags added; when the project is available to everyone, it returns every active person except the ones excluded individually or by tag.

query {
  getPotentialProjectOwners(projectId: "64a1b2c3d4e5f6a7b8c9d0e2") {
    id
    name
    email
  }
}

The query reads the panel of the project you pass. People granted access on a parent project are not added to a subproject’s list, so query the parent project when access is set there.

Projects

Read projects with getProject, getProjects, countProjects, and filterProjectIds. getProjectCategories lists the project categories projects are organized into, such as Client or Internal.

Query	Arguments	Returns
`getProject`	`id`	A single project
`getProjects`	`filter`, `archived`, `categoryId`	A list of projects
`countProjects`	`filter`, `archived`, `categoryId`	The number of matching projects
`filterProjectIds`	`filter`, `archived`, `categoryId`	Only the IDs of matching projects
`getProjectCategories`	none	All project categories

query {
  getProjects {
    id
    name
    level
    category {
      id
      name
    }
  }
}

The level field is the project’s depth in the hierarchy, where 0 is a top-level project. Restrict results to one category with categoryId:

query {
  getProjects(categoryId: "64a1b2c3d4e5f6a7b8c9d0e1") {
    id
    name
  }
}

query {
  getProjectCategories {
    id
    name
    levelNames
  }
}

Tasks

Read tasks with getTask, getTasks, countTasks, and filterTaskIds. getTaskCategories lists the task categories, which Beebole calls plannings.

Query	Arguments	Returns
`getTask`	`id`	A single task
`getTasks`	`filter`, `archived`, `startTime`, `endTime`, `categoryId`	A list of tasks
`countTasks`	`filter`, `archived`, `startTime`, `endTime`, `categoryId`	The number of matching tasks
`filterTaskIds`	`filter`, `archived`, `categoryId`	Only the IDs of matching tasks
`getTaskCategories`	none	All task categories

On getTasks and countTasks, startTime and endTime (millisecond timestamps) keep the tasks whose dates overlap the window: a task is returned when it ends at or after startTime and starts at or before endTime, so a task that runs across either edge of the window is included.

query {
  getTasks {
    id
    name
    startTime {
      ts
      iso
    }
    endTime {
      ts
      iso
    }
    status {
      id
      name
    }
  }
}

query {
  getTask(id: "64a1b2c3d4e5f6a7b8c9d0e1") {
    id
    name
    effort
    dependencies {
      id
      name
    }
  }
}

Query	Arguments	Returns
`getTag`	`id`	A single tag
`getTags`	`filter`, `archived`, `categoryId`	A list of tags
`countTags`	`filter`, `archived`, `categoryId`	The number of matching tags
`filterTagIds`	`filter`, `archived`, `categoryId`	Only the IDs of matching tags
`getTagCategories`	none	All tag categories

Time records

A time record is a logged time entry for one person on a specific day, linked to projects, a task, or an absence type. Read them with getTimeRecord, getTimeRecords, and countTimeRecords. getAbsenceQuotaConsumed returns how much of each of a person’s time off allowances they have used.

Query	Arguments	Returns
`getTimeRecord`	`id`	A single time record
`getTimeRecords`	`startTime`, `endTime`, `time`, `absence`, `wfh`, `filter`	A list of time records
`countTimeRecords`	`startTime`, `endTime`, `time`, `absence`, `wfh`, `filter`	The number of matching time records
`getAbsenceQuotaConsumed`	`personId`, `absenceQuotaIds`	Time off consumed per allowance, in each allowance’s unit (days or hours)

getTimeRecords and countTimeRecords accept top-level arguments alongside filter:

startTime / endTime: Unix timestamps in milliseconds bounding the period. Both apply to the record’s start, since a record belongs to the day it starts on: a record is returned when it starts between startTime and endTime, both included. To cover a whole month, end on its last millisecond (1706745599999 for January 31, 2024).
time: when true, return only worked time (entries without an absence type).
absence: when true, return only absence entries (entries with an absence type).
wfh: when true, return only entries logged as working from home.
filter: a typed filter array (see Filtering results).

query {
  getTimeRecords(startTime: 1704067200000, endTime: 1706745599999, time: true) {
    id
    duration
    startTime {
      ts
      iso
    }
    nonBillable
    person {
      id
      name
    }
    projects {
      id
      name
    }
  }
}

duration is a number of milliseconds. startTime and endTime are BeeboleTime objects: select their subfields ts (a Unix timestamp in milliseconds) and iso (an ISO 8601 string). The person, projects, task, and absence fields resolve the related entities inline. getAbsenceQuotaConsumed takes the IDs of the person’s allowances, which you read from the person’s absenceQuotas attribute (it includes allowances inherited from tags and the organization):

query {
  getPerson(id: "64a1b2c3d4e5f6a7b8c9d0e1") {
    absenceQuotas {
      value {
        id
        startTime {
          iso
        }
        endTime {
          iso
        }
        absenceType {
          id
          name
          unit
        }
      }
    }
  }
}

Then pass the allowance IDs you want to measure:

query {
  getAbsenceQuotaConsumed(
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    absenceQuotaIds: ["64a1b2c3d4e5f6a7b8c9d0e4", "64a1b2c3d4e5f6a7b8c9d0e5"]
  )
}

It returns one number per ID, in the order you sent them, in the unit of each allowance’s absence type. The count follows the carry-forward rules: a day taken while a carried-over balance is still valid is charged to that balance and never counted twice. An ID that is not one of the person’s allowances returns 0.

Find the most recent entry on a project

getTimeRecords has no sort or limit argument and returns its records in no particular order. To find the last time someone logged time on a project, filter on the project and the person, keep the window short, and take the record with the highest startTime.ts:

query {
  getTimeRecords(
    startTime: 1719792000000
    endTime: 1727740799999
    filter: [
      { projectIds: ["64a1b2c3d4e5f6a7b8c9d0e2"], following: AND }
      { personId: "64a1b2c3d4e5f6a7b8c9d0e1" }
    ]
  ) {
    id
    duration
    startTime {
      ts
      iso
    }
  }
}

This window covers July 1 to September 30, 2024. If it returns nothing, move it further back. projectIds also matches the entries on the project’s subprojects, and leaving out the personId condition finds the last entry anyone logged on the project.

Timesheets and approvals

A timesheet is one person’s time records over one timesheet period, and its approval status — draft, submitted, approved, or rejected — belongs to the period, not to the individual records. Time records carry no status field, and getTimeRecords ignores the status input that the schema lists on its filter type. Read approval data with these queries instead:

Query	Arguments	Returns
`getApprovalState`	`personId`, `startTime`, `endTime`	The current status of one person’s period, with its stage breakdown
`getPendingApprovals`	`showAll`	Submitted timesheets waiting for the key’s owner — or every pending submission they may see, with `showAll: true`
`getTeamApprovalStates`	`personIds`, `startTime`, `endTime`	The status of several people’s timesheets for one period
`getTimesheetTeam`	`startTime`, `endTime`	The people whose timesheets the key’s owner may review for a period
`getApprovalEvents`	`personId`, `startTime`, `endTime`	Every approval event — submissions, approvals, rejections — on one person’s period
`getPersonApprovalEvents`	`personId`	All of a person’s approval events, in chronological order
`getApprovalEventById`	`id`	A single approval event
`getApprovalDigest`	`personId`, `startTime`, `endTime`	Rule-based anomalies in the period, for an approver to review before deciding
`getTimesheetScore`	`personId`, `periods`	The person’s timesheet score over recent periods (12 by default)
`canApproveTimesheets`	none	Whether the key’s owner may use the approval and team panes

The status field on approval states and events uses one-letter codes: d (draft), s (submitted), a (approved), and r (rejected). An approval event can also carry f, which marks a period that auto-submit could not process: the period stays a draft.

List timesheets awaiting approval

query {
  getPendingApprovals(showAll: true) {
    person {
      id
      name
    }
    startTime {
      ts
      iso
    }
    endTime {
      ts
      iso
    }
    status
    currentStage
    totalDuration
    submitId
  }
}

Check whether a period is still a draft

query {
  getApprovalState(
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    startTime: 1717200000000
    endTime: 1719791999999
  ) {
    status
    currentStage
    currentStageType
    submitId
  }
}

A period nobody has submitted yet returns status: "d". To find every draft in a team, call getTeamApprovalStates with the team’s personIds and keep the entries whose status is d. The submitId of a submitted period is what approveTimesheet and rejectTimesheet expect — see Mutations.

Expense records

An expense record is an expense logged by a person against a project and an expense type. Read them with getExpenseRecord and getExpenseRecords.

Query	Arguments	Returns
`getExpenseRecord`	`id`	A single expense record
`getExpenseRecords`	`startTime`, `endTime`, `filter`	A list of expense records

query {
  getExpenseRecords(startTime: 1704067200000, endTime: 1706745599999) {
    id
    date {
      ts
      iso
    }
    amount {
      value
      currency
    }
    comment
    expenseType {
      id
      name
    }
    project {
      id
      name
    }
  }
}

date is a BeeboleTime object (ts in milliseconds, iso as an ISO 8601 string). amount is an object with value (an integer in the currency’s smallest unit) and currency (an ISO 4217 code).

Billing and cost rates

A billing or cost rate is a dated amount set on the organization, a tag, a person, or a project, as described in Billing and Costs. Read rates through the billings and costs fields of currentOrganisation, tags, people, and projects. Each returns value, the list of rates that applies to the record (its own, or when it has none, the ones it inherits from a tag, a parent, or the organization), and path, the chain from the record you asked for to the one the rates are set on.

query {
  getProject(id: "64a1b2c3d4e5f6a7b8c9d0e2") {
    name
    billings {
      value {
        id
        method
        startTime {
          ts
          iso
        }
        amount {
          value
          currency
        }
        splitType
        personSplit {
          person {
            id
            name
          }
          amount {
            value
            currency
          }
          nonBillable
        }
      }
      path {
        id
        collection
        name
      }
    }
  }
}

A path with a single entry means the rates are the record’s own; otherwise its last entry is the tag, parent, or organization that holds them. Each rate’s startTime is its From date, method is hourly, daily, fixed, or nonBillable, and amount.value is an integer in the currency’s smallest unit. When splitType is set (persons, projects, or tags), personSplit, projectSplit, or tagSplit lists the separate amounts. The rate id is what the rate mutations, such as editBillingAmount, expect. Time records carry no amount, only their nonBillable flag. Beebole computes billing and cost in reports, from the rate that covers each entry’s date.

Absence types

Absence types are the kinds of leave people can log against, such as vacation or sick leave. Read them with getAbsenceType, getAbsenceTypes, and countAbsenceTypes.

Query	Arguments	Returns
`getAbsenceType`	`id`	A single absence type
`getAbsenceTypes`	`filter`, `archived`	A list of absence types
`countAbsenceTypes`	`filter`, `archived`	The number of matching absence types

query {
  getAbsenceTypes {
    id
    name
    unit
    involveCosts
  }
}

unit is day or hour.

Custom fields

Custom field definitions and the values stored on records are separate entities. Read definitions with getCustomField, getCustomFields, and countCustomFields; read values with getCustomFieldValue, getCustomFieldValues, and countCustomFieldValues.

Query	Arguments	Returns
`getCustomField`	`id`	A single custom field definition
`getCustomFields`	`filter`, `archived`	All custom field definitions
`countCustomFields`	`filter`	The number of matching definitions
`getCustomFieldValue`	`id`	A single stored value
`getCustomFieldValues`	`filter`	Stored values, optionally filtered by field, entity type, or entity
`countCustomFieldValues`	`filter`	The number of matching values

A value’s entityType is one of Person, Project, Task, Tag, TimeRecord, or AbsenceType, and entityId is the record it sits on. The definition’s fieldType is text, number, date, datetime, url, boolean, or uniqueId, and the value itself lives in the matching field: textValue (for text and uniqueId), numberValue, dateValue, dateTimeValue, urlValue, or booleanValue. The person, project, task, tag, timeRecord, and absenceType fields resolve the owning record inline — only the one matching entityType is set.

query {
  getCustomFields {
    id
    name
    fieldType
    archived
  }
}

Look up records by an external identifier

Beebole has no built-in external ID attribute: an identifier from another system lives in a text or Unique ID custom field (a migrated legacy account gets a text field named External ID). To find the record that carries a given identifier, filter the field’s values on customFieldId and textValue. The textValue filter matches the whole stored value, ignoring upper and lower case and any spaces around it:

query {
  getCustomFieldValues(
    filter: [
      { customFieldId: "64a1b2c3d4e5f6a7b8c9d0e1", following: AND }
      { textValue: "EMP-0042" }
    ]
  ) {
    entityType
    entityId
    textValue
    person {
      id
      name
      email
    }
  }
}

The matching row’s entityId is the Beebole record, and person resolves it inline when entityType is Person (use project, task, and the other entity fields for other types). On a Unique ID field, at most one record matches. To read the values on one known record instead, filter by entityType and entityId. Writing values is covered under Custom fields on the Mutations page.

Filtering results

The filter argument is a list of typed input objects, not a list of field/value pairs. Each entity has its own filter input type, such as BeeboleTimeRecordFilter, BeebolePersonFilter, or BeeboleProjectFilter. You set the named fields you want to match directly on each object.

query {
  getTimeRecords(filter: [{ personId: "64a1b2c3d4e5f6a7b8c9d0e1" }]) {
    id
    duration
    startTime {
      ts
      iso
    }
  }
}

Each object in the array sets exactly one matching field: an object with two fields fails with OnlyOnePropertyPerFilterAllowed. To combine conditions, add a following value of AND or OR to chain one condition to the next, and leave following off the last object (an object without it anywhere else fails with IncorrectFilter). AND binds before OR, so A AND B OR C reads as (A AND B) OR C:

query {
  getProjects(
    filter: [
      { categoryId: "64a1b2c3d4e5f6a7b8c9d0e1", following: AND }
      { archived: false }
    ]
  ) {
    id
    name
  }
}

Time record filter fields

BeeboleTimeRecordFilter accepts these fields (each optional):

Field	Type	Matches
`id` / `notId`	`BeeboleId`	A specific time record, or all but one
`personId` / `notPersonId`	`BeeboleId`	Records for (or excluding) one person
`personIds`	`[BeeboleId]`	Records for any of several people
`startTime` / `endTime`	`BeeboleTimestamp`	Records starting at or after / at or before a millisecond timestamp (both bounds apply to the record’s start)
`projectIds` / `notProjectIds`	`[BeeboleId]`	Records on (or excluding) projects, including their subprojects
`taskIds` / `notTaskIds`	`[BeeboleId]`	Records on (or excluding) tasks
`projectTagIds` / `projectNotTagIds`	`[BeeboleId]`	Records whose projects carry (or lack) given tags
`personTagIds` / `personNotTagIds`	`[BeeboleId]`	Records whose person carries (or lacks) given tags
`projectCategoryIds` / `notProjectCategoryIds`	`[BeeboleId]`	Records by project category
`taskCategoryIds` / `notTaskCategoryIds`	`[BeeboleId]`	Records by task category
`wfh`	`Boolean`	Records logged (or not) as working from home
`nonBillable`	`Boolean`	Records marked (or not) as non-billable
`following`	`AND` / `OR`	Logical operator chaining this condition to the next

The schema also lists isAbsence, status, and billable on this input, but getTimeRecords and countTimeRecords don’t filter on them: status and billable are ignored, and isAbsence matches no record. Separate worked time from absences with the top-level time and absence arguments, and read approval status with the queries under Timesheets and approvals.

Other filter types

Every other entity exposes a filter input tuned to its own fields. All fields are optional, name is a case-insensitive regular expression (so Acme also matches Acme Corp), and following chains conditions the same way.

Filter input	Fields
`BeebolePersonFilter`	`id`, `notId`, `name`, `archived`, `roleId`, `tagIds`, `notTagIds`, `scheduleTypeId`
`BeeboleProjectFilter`	`id`, `notId`, `name`, `level`, `archived`, `categoryId`, `tagIds`, `notTagIds`, `assignedPersonId`, `managedById`, `subProjectId`
`BeeboleTaskFilter`	`id`, `notId`, `name`, `level`, `archived`, `categoryId`, `statusId`, `notStatusId`, `ownerId`, `ownerIds`, `notOwnerId`, `ownerTagId`, `notOwnerTagId`, `assignedPersonId`, `notAssignedPersonId`, `assignedTagId`, `notAssignedTagId`, `projectId`, `projectIds`, `notProjectId`, `assignedProjectId`, `childrenOfId`, `startsBefore`, `endsAfter`, `tagIds`, `notTagIds`, `taskTagIds`, `notTaskTagIds`, `personTagIds`, `notPersonTagIds`, `projectTagIds`, `notProjectTagIds`, `projectCategoryIds`, `notProjectCategoryIds`, `taskCategoryIds`, `notTaskCategoryIds`
`BeeboleTagFilter`	`id`, `notId`, `name`, `level`, `archived`, `categoryId`, `scheduleId`, `taggedPersonId`, `taggedProjectId`, `taggedTaskId`
`BeeboleExpenseRecordFilter`	`id`, `notId`, `personId`, `notPersonId`, `projectId`, `notProjectId`, `projectTagIds`, `projectNotTagIds`, `personTagIds`, `personNotTagIds`
`BeeboleAbsenceFilter`	`id`, `notId`, `name`, `archived`
`BeeboleCustomFieldFilter`	`id`, `name`, `archived`
`BeeboleCustomFieldValueFilter`	`id`, `customFieldId`, `entityType`, `entityId`, `notEntityId`, `textValue`

For example, the projects that have a given person among their managers:

query {
  getProjects(filter: [{ managedById: "64a1b2c3d4e5f6a7b8c9d0e1" }]) {
    id
    name
  }
}

Browse every filter type and its fields in the Schema explorer.

Counting and ID-only queries

For most entities (expense records are the exception), alongside the full get… query you also get a counterpart that returns just a count, and (for people, projects, tasks, and tags) one that returns only matching IDs.

The count… queries (countPersons, countProjects, countTasks, countTags, countTimeRecords, countAbsenceTypes, countCustomFields, countCustomFieldValues) return an integer. Use them to size a result set before fetching it.
The filter…Ids queries (filterPersonIds, filterProjectIds, filterTaskIds, filterTagIds) return an array of IDs instead of full objects, which is lighter when you only need identifiers.

query {
  countTimeRecords(startTime: 1704067200000, endTime: 1706745599999)
}

The Beebole query API has no pagination — there are no limit, offset, first, or cursor arguments. A list query returns every record that matches its arguments. Narrow large result sets with filter, the startTime / endTime window, or categoryId, and use a count… query first to gauge the size.

API Introduction

Authenticate with an API key and send your first request.

Mutations

The write operations that create, update, archive, and delete records.

Schema explorer

Browse every query, type, field, and filter input interactively.

GraphQL API

Examples

MCP & Webhooks

Legacy

Querying time records, projects, and people

Organization

People

List the people who have access to a project

Projects

Tasks

Tags

Time records

Find the most recent entry on a project

Timesheets and approvals

List timesheets awaiting approval

Check whether a period is still a draft

Expense records

Billing and cost rates

Absence types

Custom fields

Look up records by an external identifier

Filtering results

Time record filter fields

Other filter types

Counting and ID-only queries

API Introduction

Mutations

Schema explorer

​Organization

​People

​List the people who have access to a project

​Projects

​Tasks

​Tags

​Time records

​Find the most recent entry on a project

​Timesheets and approvals

​List timesheets awaiting approval

​Check whether a period is still a draft

​Expense records

​Billing and cost rates

​Absence types

​Custom fields

​Look up records by an external identifier

​Filtering results

​Time record filter fields

​Other filter types

​Counting and ID-only queries

​Related content

API Introduction

Mutations

Schema explorer

Organization

People

List the people who have access to a project

Projects

Tasks

Tags

Time records

Find the most recent entry on a project

Timesheets and approvals

List timesheets awaiting approval

Check whether a period is still a draft

Expense records

Billing and cost rates

Absence types

Custom fields

Look up records by an external identifier

Filtering results

Time record filter fields

Other filter types

Counting and ID-only queries

Related content