Data Export API response fields

Each Data Export API endpoint returns a JSON array of objects. Use the tables in this topic to interpret the fields in each response.

Conventions used in this reference

  • All durations are reported in milliseconds.
  • All date and time values are formatted in the timezone specified by the timezone request parameter, using the pattern YYYY-MM-DDTHH:MM:SS.sss.
  • Identifier fields (printerId, jobId) are stable across requests and can be cached by integrating applications. printerId never changes, so values can be stored and reused across sessions.

GET /printers response fields

The /printers endpoint returns one object per printer identified in the account and tracked by a data collector.

Field Type Description
printerName string The display name assigned to the printer in RICOH Predictive Insight.
printerId string (UUID) The unique identifier for the printer. Use this value as the printerId parameter when you call /jobs or /printer-states.
engines integer The number of print engines in the printer. Continuous-feed printers can have one or more engines; cut-sheet printers typically report a single engine. Each engine is reported as a separate row in /printer-states responses.
manufacturer string The manufacturer of the printer, for example Ricoh or InfoPrint.
model string The printer model as reported by the device, for example RICOH Pro VC80000.
printerMode string Whether the printer is operating in simplex or duplex mode. This field can be absent for printer types where the value does not apply, such as cut-sheet devices.
printerType string Whether the printer supports continuous_feed or cut_sheet paper.
serialNumber string The serial number reported by the printer. For multi-engine printers, this field can include serial numbers for each engine in a single string, for example Printer 1: 10-11111 and Printer 2: 10-11112.
connectionStatus string Indicates whether RICOH Predictive Insight can currently reach the printer. Possible values are connected and not_connected.

GET /jobs response fields

The /jobs endpoint returns one object per job processed by the requested printers within the requested time range.

Field Type Description
printerId string (UUID) The identifier of the printer that processed the job. Matches a printerId from the /printers response.
jobId string The unique identifier of the job.
jobName string The name of the job as submitted to the printer, typically the source filename.
jobPrintingSide string The side or sides printed for this job, for example simplex or duplex.
jobAction string The state of the job at the time the request was processed. Possible values:
  • printing: the job was printing when the request was issued.
  • printed: the job finished printing successfully.
  • aborted: the job ended before it finished printing.
  • completed: the job reached a final state. This value is a superset that includes both printed and aborted jobs. Use it when you want to retrieve all jobs that are no longer active, regardless of outcome.
jobStartTime string (datetime) The local date and time when the job started printing, in the timezone supplied in the request.
jobEndTime string (datetime) The local date and time when the job ended, in the timezone supplied in the request.
jobDuration integer The elapsed printing time for the job, in milliseconds.
printedCopies integer The number of copies of the job produced.
printedPages integer The total number of logical pages printed for the job, including all copies.
printedImpressions integer The total number of impressions printed. An impression is one side of one sheet, so a duplex job produces two impressions per sheet.
printedSheets integer The total number of physical sheets used for the job.
printedRollFeet number For continuous-feed printers, the length of media consumed by the job, in feet.
printedRollMeters number For continuous-feed printers, the length of media consumed by the job, in meters.
inkC, inkM, inkY, inkK number The amount of cyan, magenta, yellow, and black ink consumed by the job, reported per color channel in cubic centimeters (cc).
flushingC, flushingM, flushingY, flushingK number The amount of cyan, magenta, yellow, and black ink consumed during printhead flushing operations associated with the job, reported per color channel in cubic centimeters (cc). Flushing values are tracked separately from inkC/M/Y/K so that productive ink usage can be distinguished from maintenance usage.

GET /printer-states response fields

The /printer-states endpoint returns one object per printer engine, per state interval. Which fields are present depends on the request mode:

  • Aggregated history (default): all fields are returned.
  • Current state only (currentState=true): printerStateDuration, historyStartTime, and historyEndTime are omitted.
  • State category only (stateCategoryOnly=true): printerState is omitted.
Field Type Description
printerId string (UUID) The identifier of the printer this row describes. Matches a printerId from the /printers response.
engine string The engine within the printer that this row describes, for example engine_1, engine_2, or engine_3. A printer with multiple engines returns one row per engine for each state interval.
stateCategory string The high-level category that the engine state rolls up to. Possible values are up, down, idle, and unknown. Use this field for dashboards and reporting that need consistent categories across printer models.
printerState string The raw state reported by the printer engine, such as Printing, Preparing, Maintenance, or Sleeping. Raw state values vary by printer model. Omitted when stateCategoryOnly=true.
Note: See Printer states and state categories for a complete list of states and their mappings.
printerStateDuration integer The length of time the engine remained in this state, in milliseconds. Omitted when currentState=true.
historyStartTime string (datetime) The local date and time when the engine entered this state, in the timezone supplied in the request. Omitted when currentState=true.
historyEndTime string (datetime) The local date and time when the engine left this state, in the timezone supplied in the request. For the most recent interval in an aggregated response, this value can equal the end of the requested time range. Omitted when currentState=true.

In this section:

  1. Printer states and state categories
    The /printer-states endpoint reports both a raw printer state and a high-level state category. Use the tables in this topic to understand which raw states roll up into which categories.
  2. Working with Data Export API response limits
    The Data Export API does not paginate responses. If a request would return more data than the API permits in a single response, the request fails with an error rather than returning a partial result. Plan your integrations to stay within the limits by narrowing the date range, reducing the number of printers per request, or both.
Parent topic: Working with the Data Export API – BETA