Get Tracking
This endpoint provides information about the plan and pack usage details for a particular group. It will give you information about the number of available resources (such as documents, pages, etc. – depending on what your plan(s)/packs(s) are configured with) for the group.
POST Parameters
| Parameter | Required | Value | Description |
|---|---|---|---|
api_key | {key} | An API key that has access to the resource you want to query for | |
workflow_id | {integer} | The group you wish to get the usage details for. If not submitted then the group of the API key will be used. | |
document_id | {integer} | The document you wish to get the tracking details for. | |
status | ok, error, blank, resolved | The status of the items you wish to show. Usually this is set to error | |
type | email, ftp, web, api | You can choose whether to filter results based on a specific way in which items entered the system (using different input methods). Note: Mobile app is "api" | |
page | {integer} | If the number of items in the request exceeds the defined items_per_page (or exceeds the maximum allowed), define the number of page of results that you require. | |
items_per_page | {integer} (10-1000) | The maximum number of items to return. If this is exceeded then pagination will occur. The default is 20 with a minimum of 10 and maximum of 1000. | |
start_datetime | {datetime ISO 8601} | Start date time of the tracking activities returned. Format: YYYY-MM-DDThh:mm:ssTZD (e.g., 2018-01-01T01:00:00+13:00) | |
end_datetime | {datetime ISO 8601} | End date time of the tracking activities returned. Format: YYYY-MM-DDThh:mm:ssTZD (e.g., 2018-01-31T01:00:00+13:00) | |
time_covers | TimeReceived, TimeActivity | TimeReceived (default): considers document received timing to filter records. TimeActivity: considers last document activity timing to filter records. | |
order | asc, desc | Whether the returned items are sorted ascending or descending based on their document IDs (older first or newer first) | |
timezone | {php timezone} | Set the display timezone for the response datetime. All standard PHP timezones are supported. Default is "Pacific/Auckland" | |
detailed | 1, {null} | When set to "1", full information about each input is returned including email subject, body, header, activity history etc. Can be quite large from a size perspective. | |
learning | 1, {null} | Set to "1" to get the tracking activities of documents used for learning |
Important Requirements:
- Either workflow_id OR document_id must be provided (⚠️ indicates at least one is required)
- All datetime parameters use ISO 8601 format with timezone offset
Code Examples
The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.
Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.
curl --request POST 'https://api-app.xtracta.com/v1/tracking' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'api_key=<API_KEY>' \ --data-urlencode 'workflow_id=<WORKFLOW_ID>' \ --data-urlencode 'timezone=Pacific/Auckland'
Sample Requests
With detailed = NULL
POST https://api-app.xtracta.com/v1/tracking HTTP/1.1 api_key=123&workflow_id=123&timezone=Pacific%2FAuckland
With detailed = 1
POST https://api-app.xtracta.com/v1/tracking HTTP/1.1 api_key=123&workflow_id=123&timezone=Pacific%2FAuckland&detailed=1
Sample Responses
With detailed = NULL
<?xml version="1.0" encoding="UTF-8"?>
<tracking_response>
<status>200</status>
<message>The request has been successfully processed</message>
<page>1</page>
<items_per_page>20</items_per_page>
<items_matching_query>2</items_matching_query>
<input>
<id>2309274</id>
<type>email</type>
<received>2015-03-17T00:00:05+13:00</received>
<status>OK</status>
<file>
<status>Done</status>
<filename>wp_201sdsd6_23_59_28_pro.jpg</filename>
<file_url>https://files.example.com/demo.jpg</file_url>
<document_id>6439060</document_id>
<document_status>indexing</document_status>
</file>
</input>
<input>
<id>2306056</id>
<type>email</type>
<received>2015-03-16T01:59:25+13:00</received>
<status>OK</status>
<file>
<status>Done</status>
<filename>INV-973003_16032015.pdf</filename>
<file_url>https://files.example.com/lasdmfs1Z.pdf</file_url>
<document_id>6429771</document_id>
<document_status>indexing</document_status>
</file>
</input>
</tracking_response>
With detailed = 1
<?xml version="1.0" encoding="UTF-8"?>
<tracking_response>
<status>200</status>
<message>The request has been successfully processed</message>
<page>1</page>
<items_per_page>20</items_per_page>
<items_matching_query>2</items_matching_query>
<input>
<id>2309274</id>
<type>email</type>
<received>2015-03-17T00:00:05+13:00</received>
<status>OK</status>
<file>
<status>Done</status>
<filename>wp_2012526_23_59_28_pro.jpg</filename>
<file_url>https://files.example.com/gu4124dXUy.jpg</file_url>
<document_id>6439060</document_id>
<document_status>indexing</document_status>
<document_last_activity>2025-08-04T11:04:42+12:00</document_last_activity>
<activity>
<description>Assigned Doc ID</description>
<username>System</username>
<time>2015-03-17T00:01:40+13:00</time>
</activity>
<activity>
<description>DataEntry Ready</description>
<username>System</username>
<time>2015-03-17T00:07:30+13:00</time>
</activity>
</file>
</input>
</tracking_response>
Schema Definition
Schema Definition
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:complexType name="ActivityType">
<xs:sequence>
<xs:element name="description" type="xs:string" minOccurs="0"/>
<xs:element name="username" type="xs:string" minOccurs="0"/>
<xs:element name="time" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="FileType">
<xs:sequence>
<xs:element name="status" type="xs:string"/>
<xs:element name="filename" type="xs:string"/>
<xs:element name="file_url" type="xs:anyURI"/>
<xs:element name="document_id" type="xs:string"/>
<xs:element name="document_status" type="xs:string"/>
<xs:element name="document_last_activity" type="xs:string" minOccurs="0"/>
<xs:element name="activity" type="ActivityType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="InputType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:element name="type" type="xs:string"/>
<xs:element name="received" type="xs:string"/>
<xs:element name="status" type="xs:string"/>
<xs:element name="file" type="FileType" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="from" type="xs:string" minOccurs="0"/>
<xs:element name="subject" type="xs:string" minOccurs="0"/>
<xs:element name="body" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:element name="tracking_response">
<xs:complexType><xs:sequence>
<xs:element name="status" type="xs:positiveInteger"/>
<xs:element name="message" type="xs:string"/>
<xs:element name="page" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="items_per_page" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="items_matching_query" type="xs:nonNegativeInteger" minOccurs="0"/>
<xs:element name="input" type="InputType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence></xs:complexType>
</xs:element>
</xs:schema>
Error Responses
For JSON and XML responses generated by this endpoint, the response is wrapped in tracking_response and includes the HTTP status code and a message.
| Status | Message | Description |
|---|---|---|
400 | <parameter> must be natural number | Workflow, document, pagination, and learning values must use supported positive integers. |
400 | <parameter> must be one of the values of [...] | Use a supported status, type, order, timezone, or time_covers value. |
400 | <parameter> must be '0' or '1' | detailed accepts only 0 or 1. |
400 | Invalid date format | Supply start_datetime and end_datetime in a supported date-time format. |
400 | workflow_id and document_id can not be specified at same time | Supply exactly one selector. |
400 | Neither valid workflow_id nor document_id is specified | Supply workflow_id or document_id. |
404 | No such document found(...) | Check the document ID and API-key access. |
500 | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the selector and request timestamp if it persists. |
Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.