Search

Use this route to retrieve aggregated or summarised values for a given search view (eg jobs, quotes).

You need the information from getReportSetup to construct a report request accurately, so ensure you have it before calling this route. getReportSetup results are stable for the duration of a session (they only change when a new product release ships), so fetch it once and reuse it for subsequent reports rather than re-fetching before every call. Use cases for this route might be: How many jobs are there in the system? What's the total and average value of all my invoices that were issued last month? Give me a monthly breakdown of the total time spent on all my jobs.

post/report

Request

  • Base URL: https://api.streamtime.net/v2
  • URL: https://api.streamtime.net/v2/report
  • Auth: HTTP bearer

Query parameters

search_view'jobs' | 'job_items' | 'job_item_users' | 'job_item_roles' | 'time' | 'expenses' | 'quotes' | 'invoices' | 'job_groups' | 'companies' | 'contacts' | 'users'

What are you reporting on?

The data you are reporting on.

time_breakdownboolean

If true, returns results split into time based breakdowns based on the report's start and end dates (eg daily, weekly, monthly breakdowns). The duration of the breakdowns is automatically calculated based on the total duration of the search, eg short searches will get daily breakdowns, and longer searches will get monthly. If false, it will just return the totals for the entire time period.

Request body

startDatestring date

Optional. The start date for the report, in YYYY-MM-DD format. If you provide a date range you must also provide dateField so the report knows which date column the range applies to. Omit the dates entirely to report across all time.

endDatestring date

Optional. The end date for the report, in YYYY-MM-DD format. See startDate.

groupBystring

Optional. The column used to group the results, chosen from the groupingOptions returned by getReportSetup. OMIT this for a single grand total - e.g. for 'how many jobs do I have?' send no groupBy and you get just the totals (one number), not a row per job. When you DO want a breakdown, pick a dimension with relatively few distinct values, such as job_status (returns a handful of rows like In Play / Complete / Paused, each with its count). Avoid grouping a view by its own per-record identifier - it produces one row per record (potentially thousands) and is equivalent to just listing them. For example don't group jobs by job_id, or quotes by quote_id. Grouping by the id of a RELATED entity is fine and useful (e.g. grouping quotes by job_id to see quotes-per-job, or jobs by company_id to see jobs-per-company). Either way the response includes a 'totals' object with the grand total across all groups.

dateFieldstring

The date column that startDate/endDate apply to (eg job_start_date to report on jobs starting within the range). Must be one of the dateFieldOptions from getReportSetup. Required when startDate or endDate is provided; omit it when you aren't filtering by a date range.

querystring

The search query used to filter the records included in the report.

Example request

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "groupBy": "job_status",
  "dateField": "job_start_date",
  "statistics": [
    {
      "mode": "sum",
      "column": "job_total_planned_time_ex_tax"
    }
  ],
  "query": "job_status = 'In Play' AND job_start_date >= '2023-01-01' AND job_start_date <= '2023-12-31' AND (job_total_planned_time_ex_tax > 0 or job_name contains 'account management')"
}

Response

Search has been performed successfully.

Changes

No recorded changes to this operation across all 1 revision of this API.