Configuring a REST API collector

the rest api collector in factry historian allows you to collect data by querying a rest api endpoint once configured, the data is historized and made available for further processing in factry historian, and for trending, reporting, and analysis prerequisites permissions in factry historian to manage collectors see docid\ k2nnyecuxqqsiuclmpfkh an installed rest api collector if you have not done so already, first docid\ iv4 sd56tdxcqkrkcj4kv a working rest api endpoint if you are new to this, first test the endpoint and responses with postman or follow our guide to docid\ i9igkn w y7rulqqfphxn a configured docid\ sq5uvlchyg7umi930nyml to write the collected data to configure the collector after installing the collector, you should see that the collector is in an initial state initial state and is actively running this means that the collector has established a connection to factry historian and is awaiting further configuration to configure the collector, select it from the collectors overview in factry historian and click the edit button configure the following fields timestamplayout default parsing layout for timestamps used by this collector if empty, rfc3339 is assumed options (empty) → rfc3339 custom go layout e g "2006 01 02 15 04 05" "unix" , "unixmillis" , "unixmicros" , "unixnanos" more info on go layouts https //pkg go dev/time#layout examples "" # rfc3339 (default) "2006 01 02t15 04 05z07 00" # explicit rfc3339 with tz "2006 01 02 15 04 05" # space separated datetime "unixmillis" # 1727072405123 url the default endpoint url to be queried examples get https //api example com/data post https //api example com/data/query do not put filter or paging parameters in headers use queryparameters (get) or body (post) for parameters queryparameters optional json map for get query parameters include \<starttime> and \<stoptime> when you use windowed or historic reads example (get style) { "siteid" "46", "start" "\<starttime>", "stop" "\<stoptime>", "pagesize" "500" } queryparameters should contain \<starttime> and \<stoptime> templates if these are not present, the collector will go into an error status body optional json body for post requests example (post style) { "siteid" 46, "filter" { "type" "energy" }, "range" { "start" "\<starttime>", "stop" "\<stoptime>" } } body parameters should contain \<starttime> and \<stoptime> templates, if not present the collector will go into an error status method http method to use options get (default) idempotent reads with query params post when the api expects a json body or complex filters headers optional json map of request metadata (authentication, tenant, content negotiation) common uses authentication authorization bearer … or authorization basic \<base64(user\ pass)> api keys x api key … multi tenant routing x tenant … idempotency (some apis) idempotency key … examples authorization { "authorization" "bearer 01234567 89ab cdef 0123 456789abcdef" } api key { "x api key" "abc123" } the collector normalizes content negotiation to json content type and accept are set to application/json do not put filters, paging, or time window parameters here, use queryparameters (get) or body (post) interval default interval in seconds at which api requests are sent use 1 to leave empty default 5 examples interval 5 # default fast polling interval 60 # once per minute intervaloffset offset in seconds , relative to the 0 th second, at which requests should be sent use 1 to leave empty default 1 examples 1 # no offset 10 # send at 10 use an offset to align calls on clean boundaries and to stagger multiple measurements hitting the same api historic settings (optional) defines how the collector backfills historical data leave empty for live only fields starttimehistoric — historic start time stoptimehistoric — historic stop time (used only if start is set) intervalhistoric — chunk size (seconds) for historic requests default 900 (15 min) examples (match your timestamplayout) starttimehistoric 2025 09 01t00 00 00z stoptimehistoric 2025 09 10t00 00 00z intervalhistoric 900 starttimehistoric 1725148800 # if timestamplayout = "unix" stoptimehistoric 1725926400 intervalhistoric 3600 clear starttimehistoric once backfill completes to avoid repeating it after a restart expected outcome after saving the collector shows running when requests succeed and mappings resolve, it transitions to connected if required placeholders are missing (e g , \<starttime>/\<stoptime>), status changes to error with a helpful message in the collector history panel adding measurements follow the guide on docid\ erd7kzrrhbp7oj8suhz8g troubleshooting no data returned wrong endpoint or missing query parameters will cause issues with collecting data double check the api endpoint and parameters historic data but no live data some apis deliver data with a delay, causing the collector to miss live points and only capture them during historic runs to fix this, update the docid\ sybxzdwwtncpai2hqdusc setting to also scan for new points in the past invalid timestamp format check the timestamp layout of the response of the api and update the timestamplayout setting of the collector accordingly check the https //pkg go dev/time#layout authentication errors verify credentials and refresh tokens if needed best practices test mappings with small result sets before scaling define shared settings on the collector to avoid duplicate api calls ensure timestamp layouts are explicitly configured for non rfc3339 formats limits exceeding api rate limits may result in throttling each unique measurement override may create additional api calls