Skip to content
Hoursmith Docs
APIReferenceReports

Project profitability

Project profitability. Per-project hours and value: tracked, uninvoiced and invoiced value in the client currency, plus fixed-fee value and remaining balance (CURRENT balances, not date-filtered). Archived projects, and projects of archived clients, are listed while they have time in range or are named by projectId or clientId. members (per-person billability) is returned only on the Agency plan (advancedReporting); otherwise a warning says it was omitted. Members see only their own hours on projects they belong to and no money; a userId other than their own is a 404. Any role. Plan: Studio or Agency (reports); otherwise 402. Read-only; requires a token with read scope. Unknown or repeated (non-list) query parameters, impossible dates and inverted ranges return 422 with `fields`. Money is an exact decimal string paired with its currency; amounts in different currencies are never added together and nothing is converted. Responses are private (Cache-Control: private, no-store; Vary: Authorization).

GET
/reports/projects

Authorization

BearerAuth
AuthorizationBearer <token>

Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.

In: header

Query Parameters

from?string

Inclusive start (entry date), YYYY-MM-DD.

to?string

Inclusive end (entry date), YYYY-MM-DD. Must not be before from (422).

clientId?array<>

Filter by client. Repeat the parameter for several (max 25). Unknown ids return 404.

projectId?array<>

Filter by project. Repeat the parameter for several (max 25). Unknown ids return 404.

userId?array<>

Filter by team member (user id). Repeat the parameter for several (max 25). Unknown ids return 404.

page?integer

1-based page (default 1). A page past the end returns an empty page.

perPage?integer

Rows per page (default 25).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/reports/projects"
{  "data": {    "range": {      "from": "2019-08-24",      "to": "2019-08-24"    },    "scope": "self",    "filters": {      "clientIds": [        "c055e856-96a7-4f69-80a6-b75690833d98"      ],      "projectIds": [        "b2d9859a-b2e9-4f49-b393-9a25d0eff2f8"      ],      "userIds": [        "416ebe2c-ad2f-4853-b1f3-0c3479151dfe"      ]    },    "projects": [      {        "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",        "name": "string",        "rateType": "HOURLY",        "totalSeconds": 0,        "billableSeconds": 0,        "nonBillableSeconds": 0,        "billablePercent": 0,        "currency": "str",        "trackedValue": "string",        "uninvoicedValue": "string",        "invoicedValue": "string",        "invoicedOtherCurrencies": [          {            "currency": "str",            "amount": "string"          }        ],        "fixedFeeValue": "string",        "fixedFeeRemaining": "string",        "draftReservedValue": "string"      }    ],    "members": [      {        "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",        "name": "string",        "totalSeconds": 0,        "billableSeconds": 0,        "nonBillableSeconds": 0,        "billablePercent": 0      }    ],    "pagination": {      "page": 0,      "perPage": 0,      "total": 0,      "totalPages": 0,      "hasMore": true    },    "warnings": [      "string"    ]  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
Was this page helpful?