List cost aggregates by period.

GET

/costs

const url = 'https://api-us.suiteop.com/api/v1/costs?end=2026-04-15T12%3A00%3A00Z&groupBy=day&pendingOnly=true&start=2026-04-15T12%3A00%3A00Z';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api-us.suiteop.com/api/v1/costs?end=2026-04-15T12%3A00%3A00Z&groupBy=day&pendingOnly=true&start=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

Aggregate cost rows (labor + materials + expense + other) by (member × day or week). USE for ‘what did we spend this week’, ‘who has pending approvals’, ‘team labor by department for this pay period’, ‘unapproved hours by department’. DO NOT USE for ‘tasks Maria did’ (use listTasks), ‘who’s clocked in’ (use listClockedShifts), ‘projected cost of task X’ (use previewTaskCostForAssignees). Each returned row carries laborCostCents, laborBillableCents, nonLaborCostCents, nonLaborBillableCents, totalDurationMinutes, pendingCount, approvedCount, oldestPendingAt, hasEdits, hasAutoClockOut. pendingOnly defaults to false — set true to scope to unapproved rows. Drill into a single (member, day) via getCostsForDay.

Authorizations

apiKey

Parameters

Query Parameters

departmentIds

Array<string>

<= 200 items

end

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3}(?:Z))$/

groupBy

required

string

default: day

Allowed values: day week

memberIds

Array<string>

<= 200 items

pendingOnly

required

boolean

default: true

propertyIds

Array<string>

<= 200 items

start

required

string format: date-time

string

>= 1 characters

Responses

200

Success.

application/json

object

data

required

Response payload.

Array<object>

object

approvedCount

required

number

hasAutoClockOut

required

boolean

hasEdits

required

Any of:

boolean
null

boolean

laborBillableCents

required

number

laborCostCents

required

number

memberFirstName

required

Any of:

string
null

string

memberId

required

Any of:

string
null

string

memberLastName

required

Any of:

string
null

string

nonLaborBillableCents

required

number

nonLaborCostCents

required

number

oldestPendingAt

required

Any of:

string
null

string

paidBreakMinutes

required

number

pendingCount

required

number

periodStart

required

string

rowCount

required

number

taskCount

required

number

totalDurationMinutes

required

number

unpaidBreakMinutes

required

number

meta

required

Response metadata present on every success response.

object

pagination

Present on list responses.

object

limit

required

Page size used for this request.

integer

offset

required

Number of items skipped.

integer

total

required

Total number of matching items (across all pages).

integer

requestId

required

Unique identifier for this request.

string

Example ^generated

{
  "data": [
    {
      "approvedCount": 1,
      "hasAutoClockOut": true,
      "hasEdits": true,
      "laborBillableCents": 1,
      "laborCostCents": 1,
      "memberFirstName": "example",
      "memberId": "example",
      "memberLastName": "example",
      "nonLaborBillableCents": 1,
      "nonLaborCostCents": 1,
      "oldestPendingAt": "example",
      "paidBreakMinutes": 1,
      "pendingCount": 1,
      "periodStart": "example",
      "rowCount": 1,
      "taskCount": 1,
      "totalDurationMinutes": 1,
      "unpaidBreakMinutes": 1
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "offset": 1,
      "total": 1
    },
    "requestId": "example"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute for this API key.

X-RateLimit-Remaining

integer

Remaining requests in the current rate-limit window.

X-RateLimit-Reset

integer

Unix epoch seconds when the rate-limit window resets.

X-Request-Id

string

Unique identifier for this request (matches meta.requestId in the body).

400

application/json

ValidationError

Error envelope returned for HTTP 400 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: validation_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "validation_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

401

application/json

AuthenticationError

Error envelope returned for HTTP 401 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: authentication_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

Request correlation id (also in meta.requestId).

403

application/json

AuthorizationError

Error envelope returned for HTTP 403 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: authorization_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "authorization_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

404

application/json

NotFoundError

Error envelope returned for HTTP 404 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: not_found_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "not_found_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

409

application/json

ConflictError

Error envelope returned for HTTP 409 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: conflict_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "conflict_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

422

application/json

BusinessRuleError

Error envelope returned for HTTP 422 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: business_rule_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "business_rule_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

429

application/json

RateLimitError

Error envelope returned for HTTP 429 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: rate_limit_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Number of seconds to wait before retrying.

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

500

application/json

InternalError

Error envelope returned for HTTP 500 responses.

object

error

required

object

code

required

Machine-readable error code.

string

details

Optional structured details (omitted when undefined).

object

key

additional properties

any

message

required

Human-readable error message.

string

type

required

Error type.

string

Allowed values: internal_error

meta

required

object

requestId

required

string

Example

{
  "error": {
    "type": "internal_error"
  }
}

Headers

X-RateLimit-Limit

integer

Maximum requests per minute.

X-RateLimit-Remaining

integer

Remaining requests in the current window.

X-RateLimit-Reset

integer

Unix epoch seconds when the window resets.

X-Request-Id

string

Request correlation id (also in meta.requestId).

List cost aggregates by period.

Authorizations

Parameters

Query Parameters

Responses

200

Example generated

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

422

Example

Headers

429

Example

Headers

500

Example

Headers

Example ^generated