Get a member's timesheet totals

GEThttps://api.fieldtask.example/public/v1/timesheets/range

Permissions

members:read, timesheets:read

Also available as

fieldtask_get_timesheet_range

Returns how long one member worked on each day of a date range, and the total, in seconds.

Give a member ID and a range of 1–31 calendar days. The response has one entry for every day in the range, including days with no recorded time, and a total for the range. Days are calendar days in your organization's time zone.

This is a read-only report. It has no approval status, pay rates or pay amounts, and it covers one member per request; there's no organization-wide total. To see the individual time entries behind the totals, use List timesheet entries.

Before you start

• Timesheet reads enabled by FieldTask. Where they aren't, this endpoint returns 404 resource_not_found.
• The member's ID. Find it with GET /public/v1/members. It's a membership ID, not a user account ID. Only active members can be reported on.

Permissions

Permission	Dependency in the permission map
members:read	No dependencies
timesheets:read	Depends on members:read

Request

Responses

200

OK

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

400

Bad Request

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

401

Unauthorized

Response Headers

Cache-Control

Responses must not be cached.

WWW-Authenticate
X-Request-ID

Server-generated request correlation ID.

403

Forbidden

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

404

Not Found

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

405

Method Not Allowed

Response Headers

Allow
Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

429

Too Many Requests

Response Headers

Cache-Control

Responses must not be cached.

Retry-After

Seconds before retry; present on 429 and an in-progress operation.

X-Request-ID

Server-generated request correlation ID.

503

Service Unavailable

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

Query parameters

All three parameters are required, and no others are accepted.

Parameter	What to send
member_id	The member ID of an active member, from GET /public/v1/members.
start_date	The first day to include, as YYYY-MM-DD.
end_date	The last day to include, as YYYY-MM-DD.

Choosing dates

• Both dates are included, and the range must be 1–31 days long. start_date=2026-11-01&end_date=2026-11-30 is 30 days; start_date and end_date on the same day is one day.
• end_date can't be before start_date. A range that's too long, a reversed range or a date that doesn't exist, such as 2026-02-30, is rejected with 400 invalid_query.
• Dates are calendar days in your organization's time zone, which the response returns as timezone. If the organization has no time zone set, UTC is used. You can't choose a different time zone.
• For longer periods, such as a quarter, make one request per period of up to 31 days and add the totals.

For weekly reports, use the organization's own week. The response's week_starts_on is the first day of the week configured for your organization, for example monday. Don't assume weeks start on Sunday. See Dates and times.

Reading the result

Field	Meaning
member	The member's id and current display_name.
start_date, end_date	The range you asked for.
timezone	The time zone that defines each day, as an IANA name such as America/New_York.
week_starts_on	The organization's first day of the week.
duration_unit	Always seconds.
days	One entry per day from start_date to end_date, in date order. Each has a date and a duration in seconds.
total_duration	The sum of the duration values in days.

A duration of 0 means no time was recorded for that day. To show hours, divide by 3,600: 30600 seconds is 8.5 hours.

If FieldTask can't compute the report, you get 503 temporarily_unavailable. A successful response is never a partial report, and an error is never reported as zero hours. Retry with backoff.

Totals or entries?

Use this endpoint whenever you need worked time. Don't add up the entries from List timesheet entries instead. Entries keep their full start and end times, even where they extend beyond the range, so their sum can differ from this report.

Errors

Status	code	Meaning	What to do
400	invalid_query	A parameter is missing, repeated or unknown, a date isn't a valid YYYY-MM-DD date, end_date is before start_date, or the range is longer than 31 days.	Send member_id, start_date and end_date once each, for a range of 1–31 days.
401	invalid_token	The bearer token is missing, malformed, expired, revoked or issued for a different resource (for example an MCP sign-in).	Send a current REST API token or REST OAuth access token as Authorization: Bearer ….
403	api_access_not_enabled	FieldTask hasn't enabled API access for this organization, or has disabled it.	An owner or admin requests access in Settings → API connections.
403	insufficient_scope	The connection lacks timesheets:read or members:read. error.code is missing_permission.	Add the permission named in error.message to the connection in Settings → API connections.
404	resource_not_found	member_id isn't the ID of an active member of your organization (for example a user account ID, or a removed member), or timesheet reads aren't enabled in this environment.	Look the person up with GET /public/v1/members and use their id.
405	method_not_allowed	This path doesn't accept the HTTP method, or the create isn't enabled in this environment. The Allow header lists the methods that are.	Use a method listed in Allow.
429	rate_limit_exceeded	Too many requests in the current minute, or too many concurrent requests, for the organization or connection.	Wait for Retry-After seconds, then retry.
429	daily_quota_exceeded	The organization or connection has used its daily allowance for this kind of request. Allowances reset at 00:00 UTC.	Wait for Retry-After seconds, or check remaining allowance in Settings → API connections.
503	temporarily_unavailable	FieldTask couldn't compute the report. No partial or zero result is returned in its place.	Retry with exponential backoff.

Request

# Daily and total worked seconds for one member, Monday 2 to Sunday 8 November 2026.
# Dates are calendar days in your organization's time zone.
curl --get "$FIELDTASK_API_ORIGIN/public/v1/timesheets/range" \
  --header "Authorization: Bearer $FIELDTASK_API_TOKEN" \
  --data-urlencode "member_id=33333333-3333-4333-8333-333333333333" \
  --data-urlencode "start_date=2026-11-02" \
  --data-urlencode "end_date=2026-11-08"

Response200 OK

One week for one member

{
  "data": {
    "member": {
      "id": "33333333-3333-4333-8333-333333333333",
      "display_name": "Alex Example"
    },
    "start_date": "2026-11-02",
    "end_date": "2026-11-08",
    "timezone": "America/New_York",
    "week_starts_on": "monday",
    "duration_unit": "seconds",
    "total_duration": 140400,
    "days": [
      {
        "date": "2026-11-02",
        "duration": 28800
      },
      {
        "date": "2026-11-03",
        "duration": 30600
      },
      {
        "date": "2026-11-04",
        "duration": 27000
      },
      {
        "date": "2026-11-05",
        "duration": 28800
      },
      {
        "date": "2026-11-06",
        "duration": 25200
      },
      {
        "date": "2026-11-07",
        "duration": 0
      },
      {
        "date": "2026-11-08",
        "duration": 0
      }
    ]
  }
}

Example values. IDs and times will differ in your organization.

Try itRequest builder

1. Set the base URL to your API origin with Edit. 2. Paste your token. 3. Fill in parameters or the body. 4. Press Send API Request, or copy the request below and run it yourself. Your token is only kept on this page. Sends are real requests: a create makes a real record.

Loading the request builder…