Skip to content

Getting Started

The Data Reporting API provides a simple method to retrieve XOi step data for data analysis platforms. The REST endpoint utilizes JSON syntax.

The endpoint returns XOi Job, organization, and step data for each Workflow Job requested. For the API to return data related to Workflow Steps, those steps must be configured in XOi with a Reference Key. Only steps with a Reference Key set will be included in the data returned by the API, and steps without a Reference Key will not be included.

Best Practices

To collect the necessary Job IDs, the Job API queries can be used. However, for optimal utilization of the Data Reporting API, it is recommended to listen to change notifications through webhooks. By configuring your endpoint to receive webhook payloads, you will automatically receive the essential Job IDs within the payload.

Please contact your XOi Account Manager to configure the steps and the webhook endpoint for this API.

API Endpoint

GET https://api-jobs-external.xoi.io/prod/reporting-data/job/{cjobId}/workflow-job/{wjobId}

Authentication

Each request must include a valid access token. Please see our Authentication API Guide for more information.

Reference Keys

The Reference Key is used to categorize and identify any data captured on the step. You determine what the Reference Keys are when collaborating with your XOi Account Manager.

Requirements

  • The Key has a 64-character length limit.
  • The Key must be unique across all steps in a workflow.

Example

Each Reference Key is returned nested in the stepData object. In the example below, indoorVoltage is the Reference Key.

"indoorVoltage": {
    "value": 15,
    "unit_type": "Power",
    "unit": "Amps"
}, ...

Limitations

Currently, the data points below are not returned in this API. However, the data below is available in our GraphQL Jobs API.

  • Step Notes
  • Workflow Notes
  • Video Transcripts

Besides “Content Only” steps, any workflow steps with “extract dataplate text” enabled will not be returned in the API. Instead, add a “Content Only” step separately to capture dataplate information.

Note: If any step is empty but has a reference key enabled, it will return as null . If no steps have a Reference Key set, stepData is returned as None.