---
title: "Use this route to retrieve aggregated or summarised values for a given search view (eg jobs, quotes)."
method: POST
path: "/report"
tags: ["Search"]
---

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

`POST /report`

## Request

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

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.

## 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?
- `time_breakdown` boolean

## Request body

- object
  - `startDate` string, 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.
  - `endDate` string, date: Optional. The end date for the report, in YYYY-MM-DD format. See startDate.
  - `groupBy` string: 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.
  - `dateField` string: 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.
  - `statistics` object[], required: The statistics to calculate for each group.
    - `mode` 'count' | 'sum' | 'average' | 'min' | 'max' | 'standard_deviation': The aggregation mode to apply to the selected column.
    - `column` string: The column the aggregation mode is applied to. Refer to getReportSetup for the list of options. Only required to be passed if the mode is not count
  - `query` string: The search query used to filter the records included in the report.

## Response `200`

Search has been performed successfully.

---

[API](https://skmtc.dev/streamtime/apis/public-api.md) · [All operations](https://skmtc.dev/streamtime/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/streamtime/apis/public-api/revisions/cda8d1405534?raw)