servicepytan.reports module

servicepytan.reports.get_report_categories(conn=None)

Get a list of report categories from ServiceTitan.

Retrieves all available report categories from the ServiceTitan reporting API. These categories are used to organize reports and are required for accessing specific reports.

Parameters:

conn – Dictionary containing the credential configuration

Returns:

JSON response containing list of report categories

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> categories = get_report_categories(conn)
>>> for category in categories['data']:
...     print(category['name'])

servicepytan.reports.get_report_list(report_category, conn=None)

Get a list of reports for a given report category.

Retrieves all available reports within a specific category from the ServiceTitan reporting API.

Parameters:

• report_category – The category ID or name to retrieve reports for

• conn – Dictionary containing the credential configuration

Returns:

JSON response containing list of reports in the category

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> reports = get_report_list("jobs", conn)
>>> for report in reports['data']:
...     print(f"{report['id']}: {report['name']}")

servicepytan.reports.get_dynamic_set_list(dynamic_set_id, conn=None)

Get a list of dynamic value sets for report parameters.

Retrieves the available values for dynamic parameters in ServiceTitan reports. Dynamic sets contain the possible values that can be selected for certain report parameters.

Parameters:

• dynamic_set_id – The ID of the dynamic value set to retrieve

• conn – Dictionary containing the credential configuration

Returns:

JSON response containing the dynamic value set data

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> dynamic_values = get_dynamic_set_list("employees", conn)
>>> for value in dynamic_values['data']:
...     print(f"{value['id']}: {value['name']}")

class servicepytan.reports.Report(category, report_id, conn=None)

Bases: object

Primary class for retrieving Reporting Endpoint Data.

Provides a comprehensive interface for working with ServiceTitan reports, including parameter management, metadata retrieval, and data extraction.

category

A string representing the report category. Find list of categories with get_report_categories().

report_id

A string representing the report id. Find list of report_id using get_report_list().

conn

a dictionary containing the credential config.

__init__(category, report_id, conn=None)

Initialize Report with category, report ID, and connection configuration.

Parameters:

• category – The report category (e.g., “jobs”, “customers”)

• report_id – The specific report ID within the category

• conn – Dictionary containing the credential configuration

add_params(name, value)

Add or update a parameter for the report.

Adds a new parameter to the report’s parameter list. If the parameter already exists, it updates the existing value.

Parameters:

• name – The parameter name as defined in the report metadata

• value – The value to set for the parameter

Examples

>>> report = Report("jobs", "job-summary", conn)
>>> report.add_params("StartDate", "2024-01-01")
>>> report.add_params("BusinessUnit", "12345")

update_params(name, value)

Update an existing parameter in the report.

Updates the value of an existing parameter. If the parameter doesn’t exist, it will be added to the parameter list.

Parameters:

• name – The parameter name to update

• value – The new value for the parameter

Examples

>>> report.update_params("StartDate", "2024-02-01")

get_params()

Get the current report parameters.

Returns the current parameter configuration for the report.

Returns:

Dictionary containing the report parameters

Return type:

dict

Examples

>>> current_params = report.get_params()
>>> print(current_params)

get_metadata()

Get report metadata including available parameters and their types.

Retrieves comprehensive metadata about the report, including parameter definitions, data types, required fields, and available values.

Returns:

JSON response containing report metadata

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> metadata = report.get_metadata()
>>> for param in metadata['parameters']:
...     print(f"{param['name']}: {param['dataType']}")

show_param_types()

Display parameter types and requirements in a formatted way.

Prints a formatted list of all report parameters showing their names, data types, whether they’re required, and any available values.

Examples

>>> report.show_param_types()
>>> # Output:
>>> # [*] - StartDate: DateTime
>>> # [ ] - BusinessUnit: Long (dynamicSetId: 123)
>>> #   - Business Unit 1
>>> #   - Business Unit 2

get_data(params='', page=1, page_size=5000)

Get report data for a specific page.

Retrieves report data from ServiceTitan for a single page. Used internally by get_all_data() for pagination, but can be used directly for custom pagination handling.

Parameters:

• params – Parameter configuration (uses instance params if empty)

• page – Page number to retrieve (1-based)

• page_size – Number of records per page (max 5000)

Returns:

JSON response containing report data and pagination info

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> report.add_params("StartDate", "2024-01-01")
>>> page_data = report.get_data(page=1, page_size=1000)
>>> print(f"Retrieved {len(page_data['data'])} records")

get_all_data(params='', page_size=5000, timeout_min=60)

Get all report data with automatic pagination.

Retrieves all available data from the report by automatically handling pagination. Includes intelligent page size optimization and timeout protection to prevent excessively long-running requests.

Parameters:

• params – Parameter configuration (uses instance params if empty)

• page_size – Number of records per page (max 5000)

• timeout_min – Maximum time in minutes before aborting the request

Returns:

Dictionary containing ‘data’ (list of records) and ‘fields’ (metadata)

Return type:

dict

Raises:

requests.HTTPError – If any API request fails

Examples

>>> report = Report("jobs", "job-summary", conn)
>>> report.add_params("StartDate", "2024-01-01")
>>> report.add_params("EndDate", "2024-01-31")
>>> all_data = report.get_all_data()
>>> print(f"Retrieved {len(all_data['data'])} total records")

>>> # For large datasets, use smaller timeout
>>> large_report_data = report.get_all_data(timeout_min=30)