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, 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`, `operations`, `argumentMatch`, `responseMatch`	Audit trail entries for the organization

query {
  currentOrganisation {
    id
    name
    locked
  }
}

getAuditTrails returns mutations performed in the account. With no startTime, it covers the last seven days; startTime selects a different seven-day window.

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 allowed to own a given 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`	People eligible to own the project

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
  }
}

Projects

Read projects with getProject, getProjects, countProjects, and filterProjectIds. getProjectCategories lists the top-level groupings projects are organised into.

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 categories (boards) tasks belong to.

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

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. getAbsenceConsumed returns how much of an absence type a person has used in a window.

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
`getAbsenceConsumed`	`personId`, `absenceId`, `startTime`, `endTime`	Absence consumed in the window, in the type’s unit

getTimeRecords and countTimeRecords accept top-level arguments alongside filter:

startTime / endTime — Unix timestamps in milliseconds bounding the period.
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: 1706745600000, time: true) {
    id
    duration
    startTime {
      ts
      iso
    }
    nonBillable
    person {
      id
      name
    }
    projects {
      id
      name
    }
  }
}

duration is an integer in 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.

query {
  getAbsenceConsumed(
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    absenceId: "64a1b2c3d4e5f6a7b8c9d0e2"
    startTime: 1704067200000
    endTime: 1735689600000
  )
}

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, so getTimeRecords has no status filter. 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).

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: 1706745600000) {
    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.

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
  }
}

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 value itself lives in the field matching the definition’s fieldType: textValue, 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 custom field (a migrated legacy account gets one named External ID). The value filter matches on customFieldId, entityType, and entityId — not on the value itself — so fetch the field’s values once and match them on your side:

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

Pick the row whose textValue equals your identifier; its entityId — and the resolved person — is the Beebole record. 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 should set a single matching field. To combine conditions, add a following value of AND or OR to chain one condition to the next:

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`	ID	A specific time record, or all but one
`personId` / `notPersonId`	ID	Records for (or excluding) one person
`personIds`	`[ID]`	Records for any of several people
`startTime` / `endTime`	Timestamp	Records starting after / ending before a millisecond timestamp
`projectIds` / `notProjectIds`	`[ID]`	Records on (or excluding) projects, including their subprojects
`taskIds` / `notTaskIds`	`[ID]`	Records on (or excluding) tasks
`projectTagIds` / `projectNotTagIds`	`[ID]`	Records whose projects carry (or lack) given tags
`personTagIds` / `personNotTagIds`	`[ID]`	Records whose person carries (or lacks) given tags
`projectCategoryIds` / `notProjectCategoryIds`	`[ID]`	Records by project category
`taskCategoryIds` / `notTaskCategoryIds`	`[ID]`	Records by task category
`isAbsence`	Boolean	Whether the record is an absence
`following`	`AND` / `OR`	Logical operator chaining this condition to the next

Other filter types

Every other entity exposes a filter input tuned to its own fields. All fields are optional, name is a case-insensitive match, 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`
`BeeboleCustomFieldFilter`	`id`, `name`, `archived`
`BeeboleCustomFieldValueFilter`	`id`, `customFieldId`, `entityType`, `entityId`

For example, the projects a person manages — the same scope a manager sees in the Budget Status report:

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

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

Counting and ID-only queries

For each major entity, 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.

count… queries (countPersons, countProjects, countTasks, countTags, countTimeRecords, countAbsenceTypes, countCustomFields, countCustomFieldValues) return an integer. Use them to size a result set before fetching it.
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: 1706745600000)
}

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

Projects

Tasks

Tags

Time records

Timesheets and approvals

List timesheets awaiting approval

Check whether a period is still a draft

Expense records

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

​Projects

​Tasks

​Tags

​Time records

​Timesheets and approvals

​List timesheets awaiting approval

​Check whether a period is still a draft

​Expense records

​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

Projects

Tasks

Tags

Time records

Timesheets and approvals

List timesheets awaiting approval

Check whether a period is still a draft

Expense records

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