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, /printer-states, or /printer-interventions.
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 and /printer-interventions 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.

GET /printer-interventions response fields

The /printer-interventions endpoint returns one object per intervention event, for each engine of each requested printer, within the requested time range.

Field Type Description
printerId string (UUID) The identifier of the printer this row describes. Matches a printerId from the /printers response.
interventionStartDate string (datetime) The local date and time when the event began, in the timezone supplied in the request.
interventionEndDate string (datetime) The local date and time when the event was resolved, in the timezone supplied in the request.
duration integer The length of time the event lasted, in milliseconds.
description string A short description of the condition that caused the warning or error, for example Media empty or Paper jam. This field is language-dependent: it is returned in the language requested by the language parameter, or in English if that parameter is omitted or the description is not available in the requested language.
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 event.
jobName string The name of the job that was printing when the event occurred. The value is an empty string when no job was involved in the event.
interventionCode string A code that identifies the condition. Unlike description, this value is language-independent, so use it when you need to group or compare events across languages. The format of the code depends on the printer: cut-sheet printers report a descriptive string such as coverOpen, and continuous-feed printers report a value such as CA00 or 40000006.

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