Performance API

The Performance API returns the numbers shown on a project’s Performance dashboard and on the workspace Monitor: throughput, time, and quality metrics over a period, and totals for each labeler and reviewer. Use it to bring those numbers into your own reporting. The API runs the same reports as the pages. For the same dates and filters it returns the same values, and the same rules decide what you can see.

Before you start

You need:

A Labelbox API key.
Access to performance data. If you can open a project’s Performance dashboard, you can read that project through the API. Workspace reports need permission to view performance across your organization, as the Monitor does.
For the Python examples, Python SDK version 7.13.0 or later.

All endpoints are GET requests under this base URL, authenticated with your API key as a bearer token:

https://api.labelbox.com/api/v1/performance

Quick start

Get the number of labels created per day in a project:

import labelbox as lb

client = lb.Client(api_key="<YOUR_API_KEY>")
project = client.get_project("<PROJECT_ID>")

series = project.get_performance_metric(
    "labels_created", "2026-01-01", "2026-01-31"
)
for bucket in series.buckets:
    print(bucket.start.date(), bucket.value)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/projects/$PROJECT_ID/metrics/labels_created?startDate=2026-01-01&endDate=2026-01-31"

The response has one bucket per day:

{
  "projectId": "<PROJECT_ID>",
  "metric": "labels_created",
  "unit": "count",
  "bucketType": "time",
  "buckets": [
    {
      "start": "2026-01-01T00:00:00.000Z",
      "end": "2026-01-02T00:00:00.000Z",
      "value": 412,
      "numerator": null,
      "denominator": null,
      "modes": null
    }
  ],
  "interval": "day",
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "generatedAt": "2026-02-01T09:30:00.000Z"
}

Endpoints

Endpoint	Python SDK	Returns
`GET /metrics`	`client.get_performance_metrics()`	The metrics you can query
`GET /projects/{projectId}/metrics/{metric}`	`project.get_performance_metric()`	One metric for a project, a value per interval
`GET /projects/{projectId}/labelers`	`project.get_labeler_performance()`	Totals for each labeler
`GET /projects/{projectId}/reviewers`	`project.get_reviewer_performance()`	Totals for each reviewer
`GET /projects/{projectId}/download`	`project.get_performance_report_download()`	A link to the report as a file
`GET /workspace/metrics/{metric}`	`client.get_workspace_performance_metric()`	One metric across your workspace
`GET /workspace/labelers`	`client.get_workspace_labeler_performance()`	Totals for each labeler on each project

Every table is paged. Filters lists which parameters each report takes. See Paging and Reliability before you build on the API.

Units and dates

Time is in seconds.
Percentages and agreement scores are fractions from 0 to 1. A value of 0.9 means 90%.
Dates are calendar days in UTC, written as 2026-01-31. Reports are bucketed by UTC day. startDate and endDate are the first and last day of the period, both included, and a request can cover at most 366 days.
Wider buckets keep their calendar bounds: a week runs from Monday, a month from the 1st. The first and last bucket of a series can reach beyond your period, but they count only the days inside it. For counts and time totals, a wider bucket is the sum of its days. Averages and percentages are worked out over the whole bucket, so they are not.

In the Python SDK you can pass a date, a datetime, or a string. A datetime with a time zone is converted to its UTC day.

Metrics

List the metrics available to you, with their units and definitions:

for metric in client.get_performance_metrics():
    print(metric.name, metric.unit, metric.description)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/metrics"

Throughput

Metric	Unit	What it measures
`done_datarows`	count	Data rows in the Done step of the workflow
`accepted_datarows`	count	Data rows in the Accepted step of the workflow
`labels_created`	count	Labels created in the period
`annotations_created`	count	Annotations created in the period
`approved_reviews`	count	Approve actions, through review tasks in the workflow, on labels created in the period
`rejected_reviews`	count	Reject actions, through review tasks in the workflow, on labels created in the period
`media_duration`	seconds	Total media duration of data rows in the Done step
`media_duration_in_review`	seconds	Total media duration of data rows currently in a Review step
`media_duration_accepted`	seconds	Total media duration of accepted data rows
`total_time`	seconds	Total labeling, review, and rework time spent on labels created in the period
`labeling_time`	seconds	Total time spent in labeling mode while the timer is on
`review_time`	seconds	Total time spent in review mode while the timer is on
`rework_time`	seconds	Total time spent in rework mode while the timer is on

Efficiency

Metric	Unit	What it measures
`avg_time_per_label`	seconds	Total labeling time divided by the number of labels worked on, including skipped and unsaved labels
`avg_review_time`	seconds	Total review time divided by the number of data rows reviewed
`avg_rework_time`	seconds	Total rework time divided by the number of data rows reworked
`aht_labeled_datarows`	seconds	Average handling time per data row with at least one label
`aht_done_datarows`	seconds	Average handling time per data row marked Done
`aht_accepted_datarows`	seconds	Average handling time per data row marked Accepted
`aht_all_labels`	seconds	Average handling time per label created, counting skipped, abandoned, and submitted labels
`aht_submitted_labels`	seconds	Average handling time per submitted label
`aht_done_labels`	seconds	Average handling time per label on done data rows
`aht_accepted_labels`	seconds	Average handling time per label on accepted data rows

Average handling time includes creating, reviewing, and reworking time. The aht_ metrics are listed and can be queried only when average handling time charts are enabled for your organization. Their buckets also carry modes, the handling time split into creating, reviewing, and reworking.

Quality

Metric	Unit	What it measures
`benchmark_percentage`	percentage	Average benchmark agreement score of labels
`benchmark_distribution`	count	Histogram of benchmark agreement scores
`consensus_percentage`	percentage	Average consensus agreement score of labels
`consensus_distribution`	count	Histogram of consensus agreement scores

The two distribution metrics return score ranges instead of time intervals. Their response has "bucketType": "score" and ten buckets, each with rangeStart, rangeEnd, and value, the number of labels whose score falls in that range. The ranges are fractions like the scores themselves: 0 to 0.1, up to 0.9 to 1.

Filters

These parameters narrow a report. Lists are comma-separated in a request, or a Python list in the SDK.

Parameter	Python SDK	Applies to	Description
`startDate`, `endDate`	`start_date`, `end_date`	All reports	Required. The period, as UTC days.
`interval`	`interval`	Metrics	Bucket width: `day` (default), `week`, `month`, `quarter`, or `year`.
`userIds`	`user_ids`	All reports	Count only work by these users. Up to 100.
`userGroupIds`	`user_group_ids`	Project reports	Count only work by the current members of these user groups. Up to 25. With `userIds` too, only users in both are counted.
`batchIds`	`batch_ids`	All reports	Count only these batches. Up to 100.
`projectIds`	`project_ids`	Workspace reports	Narrow the report to these projects. Up to 50.
`memberType`	`member_type`	Workspace reports	`internal` for members of your organization, `external` for members of other organizations. See Shared projects and workforce providers.
`ownerOrganizationIds`	`owner_organization_ids`	Workspace reports	Count only projects owned by these organizations. Up to 100.
`deletedLabels`	`deleted_labels`	All reports	`include` (default), `exclude`, or `only`.

A user group filter follows the group’s current membership. A group that is empty, is no longer attached to the project, or that you cannot view matches no work. A parameter that an endpoint does not have is refused by name, so a misspelled filter never runs an unfiltered report. A list that is sent must name at least one ID. An empty list is refused with 400 (userIds=), and the Python SDK raises ValueError for one (user_ids=[]). It is not read as “no filter”, which would report on everyone. To leave a filter off, leave the parameter out, or pass None in the SDK.

Labeler and reviewer totals

These are the two tables on the Performance dashboard: one row per member with their totals for the period.

labelers = project.get_labeler_performance(
    "2026-01-01",
    "2026-01-31",
    sort_by="labels_created",
    descending=True,
)
print(labelers.total)
for labeler in labelers:
    print(labeler.email, labeler.labels_created, labeler.avg_time_per_label)

for reviewer in project.get_reviewer_performance("2026-01-01", "2026-01-31"):
    print(reviewer.email, reviewer.labels_reviewed)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/projects/$PROJECT_ID/labelers?startDate=2026-01-01&endDate=2026-01-31&sort=labelsCreated&order=desc"

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/projects/$PROJECT_ID/reviewers?startDate=2026-01-01&endDate=2026-01-31"

Both tables are paged and sortable. See Paging. The response wraps the rows in data and adds page, perPage, and total:

{
  "projectId": "<PROJECT_ID>",
  "data": [
    {
      "userId": "<USER_ID>",
      "projectId": "<PROJECT_ID>",
      "email": "labeler@example.com",
      "memberType": "internal",
      "labelsCreated": 128,
      "labelsSkipped": 3,
      "memberTotalTime": 21640,
      "labelingTimeSubmitted": 19200,
      "labelingTimeSkipped": 240,
      "reviewsReceived": 40,
      "reviewTimeAll": 1800,
      "reworkTimeAll": 600,
      "avgTimePerLabel": 148.4,
      "avgReviewTimeAll": 45,
      "avgReworkTimeAll": 150,
      "avgBenchmarkAgreement": 0.92,
      "avgConsensusAgreement": 0.87,
      "reworkPercentage": 0.03,
      "approvalPercentage": 0.95,
      "avgRating": 4.5,
      "isRemoved": false
    }
  ],
  "page": 1,
  "perPage": 50,
  "total": 37,
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "cachedAt": null,
  "generatedAt": "2026-02-01T09:30:00.000Z"
}

Labeler fields

The Python SDK uses the same names in snake case, such as labels_created.

Field	Description
`userId`, `email`	The member. See Access and privacy for when the email is masked.
`memberType`	`internal` if the member’s account belongs to your organization, `external` if it belongs to another one. `null` if the account no longer exists.
`labelsCreated`	Labels created by the member in the period.
`labelsSkipped`	Labels skipped by the member in the period.
`memberTotalTime`	Total time the member spent in the editor during the period.
`labelingTimeSubmitted`	Labeling time spent by the member on submitted or unsaved labels.
`labelingTimeSkipped`	Labeling time spent by the member on skipped labels.
`reviewsReceived`	Approve and Reject actions, through the workflow review queue, on labels the member created.
`reviewTimeAll`	Total review time spent on labels the member created.
`reworkTimeAll`	Total rework time spent on labels the member created.
`avgTimePerLabel`	Total labeling time divided by the number of labels worked on, including skipped and unsaved labels.
`avgReviewTimeAll`	Total review time divided by the number of labels reviewed, for labels the member created.
`avgReworkTimeAll`	Total rework time divided by the number of labels reworked, for labels the member created.
`reworkPercentage`	Labels the member created that were reworked, divided by the labels they created.
`approvalPercentage`	Labels the member created that received an Approve action, divided by those with any review action.
`avgConsensusAgreement`	Average agreement with other consensus labels, for labels the member created.
`avgBenchmarkAgreement`	Average agreement with benchmark labels, for labels the member created.
`avgRating`	The member’s average rating on the project, or `null` if they have none.
`isRemoved`	`true` when the member is no longer on the project.

Reviewer fields

Field	Description
`userId`, `email`	The member.
`memberType`	`internal` or `external`, as for labelers.
`labelsReviewed`	Labels that had review time from the member in the period.
`labelsReworked`	Labels that had rework time from the member in the period.
`memberTotalTime`	Total time the member spent in the editor during the period.
`reviewTime`	Total review time spent by the member.
`reworkTime`	Total rework time spent by the member.
`avgReviewTime`	Total review time divided by the number of labels reviewed.
`avgReworkTime`	Total rework time divided by the number of labels reworked.
`reworkPercentage`	Labels reviewed by the member that were reworked, divided by the labels they reviewed.
`approvalPercentage`	Labels with an Approve action by the member, divided by labels with any review action by the member.
`isRemoved`	`true` when the member is no longer on the project.

Download the report

Get a link to the project’s performance report as a file. This is the file the Download button on the Performance dashboard gives you.

report = project.get_performance_report_download("2026-01-01", "2026-01-31")
print(report.url)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/projects/$PROJECT_ID/download?startDate=2026-01-01&endDate=2026-01-31"

The response has the url and expiresInSeconds. The link works for 24 hours.

Anyone who has the link can open the file until it expires. Treat it like the data it points to.

Workspace reports

Workspace reports are the Monitor’s data. They cover every project your organization owns and every project another organization shares with yours, or only the projects you name in projectIds.

series = client.get_workspace_performance_metric(
    "labels_created", "2026-01-01", "2026-01-31", interval="week"
)

rows = client.get_workspace_labeler_performance(
    "2026-01-01", "2026-01-31", sort_by="labels_created", descending=True
)
print(rows.total)
for row in rows:
    print(row.project_name, row.email, row.member_type, row.labels_created)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/workspace/metrics/labels_created?startDate=2026-01-01&endDate=2026-01-31&interval=week"

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/workspace/labelers?startDate=2026-01-01&endDate=2026-01-31&sort=labelsCreated&order=desc"

workspace/labelers returns one row for each labeler on each project they worked on in the period. A row has the labeler fields, without avgRating, plus:

Field	Description
`projectId`, `projectName`	The project. `projectName` is `null` for a project that can no longer be found.
`projectOrganizationId`, `projectOrganizationName`	The organization that owns the project. It is not yours for a project shared with you. Both are `null` for a project that can no longer be found.
`isProjectDeleted`	`true` when the project has been deleted. Its rows and figures stay in the report.

The table is paged like the project tables. Without sort, rows are ordered by project, then member. Workspace reports do not take a user group filter.

Shared projects and workforce providers

A project belongs to one organization and can be shared with another, for example when you add a workforce provider to it. The provider’s members then work in your project, and the project appears in the provider’s workspace as a shared project. The API reflects both sides of that connection. What a workspace report covers. The projects your organization owns, and the projects shared with it. Two fields tell them apart on every row of workspace/labelers:

projectOrganizationId is the organization that owns the project.
memberType is whose member did the work: internal for a member of your organization, external for a member of another organization or an Alignerr member. The Monitor calls external members Workforce members.

Both are told from your side. To a workforce provider its own labelers are internal, and a customer’s project has the customer’s projectOrganizationId. Alignerr members are the exception: they are external to everyone, including to Alignerr’s own organization. Split a report. Use memberType and ownerOrganizationIds on either workspace report. These are the Monitor’s Member Type and Owned by filters.

# Labels created each week by your workforce provider's members
external = client.get_workspace_performance_metric(
    "labels_created",
    "2026-01-01",
    "2026-01-31",
    interval="week",
    member_type="external",
)

# The same for your own members
internal = client.get_workspace_performance_metric(
    "labels_created",
    "2026-01-01",
    "2026-01-31",
    interval="week",
    member_type="internal",
)

# As a workforce provider: your members' totals on one customer's projects
rows = client.get_workspace_labeler_performance(
    "2026-01-01",
    "2026-01-31",
    owner_organization_ids=["<CUSTOMER_ORGANIZATION_ID>"],
    member_type="internal",
)

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/workspace/metrics/labels_created?startDate=2026-01-01&endDate=2026-01-31&interval=week&memberType=external"

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/workspace/labelers?startDate=2026-01-01&endDate=2026-01-31&ownerOrganizationIds=$CUSTOMER_ORGANIZATION_ID&memberType=internal"

A few rules apply:

A split covers members and projects with activity in the period. As on the Monitor, memberType and ownerOrganizationIds select from the members and projects that have rows in the report for your dates and other filters. If none match, every bucket is zero. It is never the unfiltered report.
A split by owner leaves out projects that are gone. A project that can no longer be found has no owner, so ownerOrganizationIds never selects it, and the splits by owner can add up to slightly less than the whole workspace.
A split by owner leaves out projects you cannot report on. Your workspace can include a project you have no role in. A metric split by ownerOrganizationIds does not count it, and lists it in skippedProjectIds so that you know.
A split of a metric needs permission to view everyone’s performance. With projectIds, memberType and ownerOrganizationIds on workspace/metrics need permission to view all performance in every project you name. Otherwise the request returns 403. On workspace/labelers they filter the rows you can already see.
Project reports carry memberType too. The labeler and reviewer tables of a project give each member’s memberType.
Names and emails are masked between a customer and a workforce provider. See Access and privacy. IDs are never masked, so you can always group and filter by userId, projectId, and projectOrganizationId.
User groups belong to the project’s organization. A userGroupIds filter on a project shared with you matches no work.

Paging

The three tables (projects/{projectId}/labelers, projects/{projectId}/reviewers, and workspace/labelers) are paged. In the Python SDK, iterating fetches one page at a time, and total gives the number of rows without reading them all:

Python

rows = client.get_workspace_labeler_performance(
    "2026-01-01", "2026-01-31", page_size=100
)
print(rows.total)
for row in rows:  # fetches page after page as you go
    ...

In a request, use these parameters:

Parameter	Description
`page`	Page number, starting at 1. Written in digits only.
`perPage`	Rows per page, up to 100. The default is 50. In the SDK, `page_size`.
`sort`	A field of the row, such as `labelsCreated`. In the SDK, `sort_by="labels_created"`.
`order`	`asc` (default) or `desc`. In the SDK, `descending=True`.
`useCache`	`false` reads the report again instead of using rows read in the last few minutes. In the SDK, `use_cache=False`. Not available on reviewers.

Every response has page, perPage, and total, the number of rows across all pages. Request pages until you have total rows. A page past the end returns an empty data.

cURL

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/performance/workspace/labelers?startDate=2026-01-01&endDate=2026-01-31&perPage=100&page=2"

Keep these in mind when you read a whole table:

Leave the cache on. The pages of workspace/labelers are cut from one reading of the report, kept for five minutes, so they agree with each other and the rows are in a fixed order. cachedAt says when that reading was taken. With useCache=false every page reads the report again.
Sorting. Every table sorts by the figures in its rows, such as labelsCreated or avgTimePerLabel, except avgRating. Without sort, the project tables come ordered by email, as on the Performance dashboard, and rows that tie under a sort are in that order too. A masked email keeps the place of the real one. workspace/labelers comes ordered by project, then member.
Metrics are not paged. A metric returns at most one bucket per day of the period, and the period is limited to 366 days.

Access and privacy

The API shows you what the pages show you.

Your own performance only. If you can only view your own performance on a project, every project report returns only your data, whatever userIds you pass.
Workspace reports. Without projectIds, you need permission to view performance across your organization. With projectIds, you need performance access to each project you name.
Projects you cannot see. A project you have no performance access to returns 404, the same as a project that does not exist.
Splitting by member type or owner. On workspace/metrics, memberType and ownerOrganizationIds need permission to view all performance in every project you name in projectIds. A project found through its owner that you cannot report on is left out and listed in skippedProjectIds.
Masked emails. The email of a member you may not identify is replaced with a masked value, as on the pages. For example, a workforce provider’s members appear masked to the project’s owner, and the owner’s members appear masked to the provider.
Masked project and organization names. A workforce provider does not see the names of the projects shared with it or of the organizations that own them. In workspace/labelers, projectName and projectOrganizationName are replaced with masked values for those projects. The IDs are unchanged.
Restricted API keys. A key created with a limited set of permissions needs a performance permission, and is limited to the ones it has. A key that only has permission to view your own performance returns only your own.

Data freshness

The API reads the same data as the Performance dashboard and the Monitor, so it is never more current than those pages. That data is rebuilt periodically, not continuously: the current day’s figures can trail real activity by anything from a quarter of an hour to over an hour. A response served from the cache can be up to five minutes older again. generatedAt is when the response was produced. cachedAt, on the labeler tables, is set when the rows came from a result computed in the last few minutes. Neither tells you how recent the underlying activity data is, and no response carries an as-of time for it. Two things follow for the current day:

Today’s bucket keeps growing. Read settled days for totals you will not revisit.
Charts and tables do not refresh together. For settled days a metric and the labeler table normally add up to the same total. For the current day they can differ until both have caught up.

Limits

Limit	Value
Period	366 days per request
`userIds`, `batchIds`	100 IDs each
`userGroupIds`	25 groups, with at most 5,000 members between them
`projectIds`	50 projects
`ownerOrganizationIds`	100 organizations
`perPage`	100 rows

Requests count toward your API rate limit, like the rest of the Labelbox API.

Reliability

Requests are safe to repeat. Every endpoint is a GET and changes nothing, so you can retry any request.
Retry 5xx responses and timeouts with a growing delay between attempts. The Python SDK does this for you, for up to four minutes, and tries once more after a request that timed out. When it stops retrying, it raises the error that kept happening.
Do not retry 4xx responses without changing the request. For 429, wait before sending more.
Allow for long requests. Reports are computed when you ask, and a long period over a large workspace can take a while. The Python SDK waits up to 120 seconds for a response.
Prefer fewer, wider requests. One request for a month at interval=day costs less than a request for each day. To read every member’s totals for a project as a file, use Download the report.
Expect new fields. Responses can gain fields over time. Ignore the ones you do not know. The Python SDK does.

Errors

Status	Meaning	Python SDK exception
`400`	A parameter is invalid. The response lists each one in `details`.	`InvalidQueryError`
`401`	The API key is missing or invalid.	`AuthenticationError`
`403`	Your role or API key does not include the permission, or you named a project in a split by member type or owner where you cannot view everyone’s performance.	`AuthorizationError`
`404`	The metric does not exist, or the project does not exist or is not visible to you.	`ResourceNotFoundError`
`429`	You have made too many requests.	`ApiLimitError`
`500`	The report could not be produced. Try again.	`InternalServerError`
`503`	Performance reports are under maintenance. Try again later.	`InternalServerError`

The Python SDK raises TimeoutError when a request gets no response in time, and NetworkError when it cannot connect. All of these exceptions are in lbox.exceptions. It raises Python’s ValueError, before sending anything, for a filter given as an empty list. A 400 response names each parameter that was refused:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid query parameters",
  "details": [
    { "parameter": "endDate", "message": "must not be before startDate" }
  ]
}

Getting started

Annotate

Model

Catalog

Schema

Import/Export

Integrations

Manage Team

Examples

Before you start

Quick start

Endpoints

Units and dates

Metrics

Throughput

Efficiency

Quality

Filters

Labeler and reviewer totals

Labeler fields

Reviewer fields

Download the report

Workspace reports

Shared projects and workforce providers

Paging

Access and privacy

Data freshness

Limits

Reliability

Errors

​Before you start

​Quick start

​Endpoints

​Units and dates

​Metrics

​Throughput

​Efficiency

​Quality

​Filters

​Labeler and reviewer totals

​Labeler fields

​Reviewer fields

​Download the report

​Workspace reports

​Shared projects and workforce providers

​Paging

​Access and privacy

​Data freshness

​Limits

​Reliability

​Errors

Before you start

Quick start

Endpoints

Units and dates

Metrics

Throughput

Efficiency

Quality

Filters

Labeler and reviewer totals

Labeler fields

Reviewer fields

Download the report

Workspace reports

Shared projects and workforce providers

Paging

Access and privacy

Data freshness

Limits

Reliability

Errors