> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/api-reference/get-started-with-tracr-search-bulk.md). # Get Started with Tracr Search Bulk The Tracr Search Bulk API allows to search for up to 1000 diamonds from multiple participants of Tracr and retrieve the history of the diamond up to the original rough. {% hint style="info" %} **You need to know** The Tracr Search Bulk API is only available for authenticated users. For more details please contact . {% endhint %} ## Before you start * Contact Tracr Support () to obtain authentication credentials. * Collect the platform ID (UUID - the participant's unique identifier) and the Tracr ID of the polished diamond(s) from the owner of the diamond(s) that you want to query. {% hint style="info" %} **Platform ID** You will need the platform ID to be able to search other user's Tracr instances. This can be collected from the URL in either UAT or Prod: `{platform_id}.uat.tracr.com` or `{platform_id}.tracr.com` {% endhint %} ## API security The API use OAuth 2.0 authentication. Tracr Support will provide a Client ID and Client Secret during the technical onboarding. ### Generate a JWT token Call `POST https://auth.tracr.com/oauth/token` {% tabs %} {% tab title="Request" %} ```json { "client_id":"", "client_secret":"", "audience":"https://search.tracr.network/v1", "grant_type":"client_credentials" } ``` {% endtab %} {% tab title="Response" %} ```json { "access_token": "", "token_type": "Bearer" } ``` {% endtab %} {% endtabs %} ### Pass the token to the endpoint To pass the token to the API, provide it in the Authorization header. ``` Authorization: ``` ## Get the ancestry for bulk diamonds Call `POST /v1/bulk/traceability-ancestry` {% tabs %} {% tab title="Request" %} ```json { "data": [ { "diamonds": [ { "diamond_id": "clitz8x970000m7yt0pu8u74e" }, { "diamond_id": "clismtsp20001lzyt6072ut87" }, { "diamond_id": "cli3lpy2i00003tzqdso2bxke" } ], "platform_id": "11111111-1111-1111-1111-111111111111", "modified_since": "2023-06-26T00:00:00+01:00" } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "results": [ { "status": "success", "platform_id": "11111111-1111-1111-1111-111111111111", "diamonds": { "cli3lpy2i00003tzqdso2bxke": [ { "diamond_id": "cli3lpjf400003oytprcxdhh8", "diamond_parent_id": null, "lifecycle_state": "split", "current_stage": "rough", "assurance_level": "assured", "provenance": { "provenance_name": "DTC", "provenance_type": "Entity", "mine_name": null }, "rough": { "carats": 8.0, "colour": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": null, "fluorescence_intensity": null, "images": [ { "filename": "demo_rough_1.jpg", "description": "Rough Diamond Picture", "hash": "32a1c0b50e7724684a96f2661bf70f67a465fd479a2e34833aedd003958bbe9d", "image_type": "default" } ], "model": null, "plan": null, "plan_reports": null, "quality": null, "scan": null, "scan_reports": null, "silhouettes": null, "stress": null, "supplementary_files": null, "videos": [ { "filename": "demo_rough_1.mp4", "description": "Rough Diamond Video", "hash": "c9806fdcfbd144eebb8a79d52956bd79bcc4dba34794a5a16294840fc6a485c0" } ] }, "polished": { "carats": null, "clarity": null, "colour": null, "crown_angle": null, "crown_height": null, "culet_condition": null, "culet_size": null, "cut_grade": null, "depth": null, "depth_percent": null, "diameter_maximum": null, "diameter_minimum": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": null, "fluorescence_intensity": null, "girdle_condition": null, "girdle_thickness_from": null, "girdle_thickness_to": null, "grading_certificates": null, "length": null, "model": null, "pavillion_angle": null, "pavillion_percent": null, "polish_quality": null, "plan": null, "plan_reports": null, "quality": null, "scan": null, "scan_reports": null, "shape": null, "silhouettes": null, "symmetry": null, "table_percent": null, "supplementary_files": null, "width": null, "images": null, "videos": null } }, { "diamond_id": "cli3lpy2i00003tzqdso2bxke", "diamond_parent_id": "cli3lpjf400003oytprcxdhh8", "lifecycle_state": "polished", "current_stage": "polished", "assurance_level": "assured", "provenance": { "provenance_name": "DTC", "provenance_type": "Entity", "mine_name": null }, "rough": { "carats": 5.123, "colour": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": null, "fluorescence_intensity": null, "images": [ { "filename": "split_demo_1.jpg", "description": "Split Diamond Picture", "hash": "9a76d5afceba756d7c1d9b26e8a654abd87c7f102878a2ab0e21a043a9d8dfcc", "image_type": "default" } ], "model": null, "plan": null, "plan_reports": null, "quality": null, "scan": null, "scan_reports": null, "silhouettes": null, "stress": null, "supplementary_files": null, "videos": null }, "polished": { "carats": 1.815, "clarity": "VVS2", "colour": "D", "crown_angle": null, "crown_height": null, "culet_condition": null, "culet_size": null, "cut_grade": "VG", "depth": 4.23, "depth_percent": 62.9, "diameter_maximum": null, "diameter_minimum": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": "N", "fluorescence_intensity": null, "girdle_condition": null, "girdle_thickness_from": "Slightly Thin", "girdle_thickness_to": null, "grading_certificates": [ { "filename": "demo_polished_1.pdf", "description": null, "hash": "1a9cbfaed6dc9fa95203a02dc3ba6ff5939a0e02ad2f433e63f3a24eaf1a0dc4", "grading_lab": "GIA", "graded_date": "2023-05-25T21:43:41", "grader_certificate_no": "GIA 215296640", "grader_report_no": "215296640", "grader_inscription_no": "GIA 215296640" } ], "length": 6.84, "model": null, "pavillion_angle": 40.8, "pavillion_percent": null, "polish_quality": "EX", "plan": null, "plan_reports": null, "quality": null, "scan": { "filename": "demo_polished_1.stl", "description": null, "hash": "7c3d05c6b1303ee0bf3ee8c2c5ae5b6a5ab3f82928d2e8b3c4d53c8b691dfdf4", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null }, "scan_reports": [ { "filename": "demo_polished_1.xml", "description": null, "hash": "feb55eba3edc6805d7f36f9b9bd540d4134fdd82d7a62fedcc504cffa4be1e03", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null } ], "shape": "Round", "silhouettes": null, "symmetry": "VG", "table_percent": 57.0, "supplementary_files": null, "width": 6.83, "images": [ { "filename": "demo_polished_1.jpg", "description": "Polished Diamond Picture", "hash": "092aa374cec6e846874ba5bdabc2cf03ad3002eaccc55e0eb8b61697763238b0", "image_type": "default" }, { "filename": "demo_polished_1_Arrows.jpg", "description": "Polished Diamond Picture", "hash": "8eefc0aac8a7ab1b723b207c1984e8d36e4aee5f1df33b7289a480eb6339cf10", "image_type": "arrow" }, { "filename": "demo_polished_1_heart.jpg", "description": "Polished Diamond Picture", "hash": "602a3a79417a7502936ddbbb9b5384f7f65f26ab70ca91f1a0ed7d3961e001b4", "image_type": "heart" } ], "videos": [ { "filename": "demo_polished_1.mp4", "description": "Polished Diamond videos", "hash": "515756198048fad606e270521e6f5b09a17e20ef4240ebfb0ac582f715179f1f" } ] } } ], "clismtsp20001lzyt6072ut87": [ { "diamond_id": "clismtsp20001lzyt6072ut87", "diamond_parent_id": null, "lifecycle_state": "polished", "current_stage": "polished", "assurance_level": "assured", "provenance": { "provenance_name": "DTC", "provenance_type": "Entity", "mine_name": null }, "rough": { "carats": 5.0, "colour": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": null, "fluorescence_intensity": null, "images": null, "model": null, "plan": null, "plan_reports": null, "quality": null, "scan": null, "scan_reports": null, "silhouettes": null, "stress": null, "supplementary_files": null, "videos": null }, "polished": { "carats": 2.159, "clarity": "VVS2", "colour": "D", "crown_angle": null, "crown_height": null, "culet_condition": null, "culet_size": null, "cut_grade": "VG", "depth": 4.21, "depth_percent": 62.4, "diameter_maximum": null, "diameter_minimum": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": "N", "fluorescence_intensity": null, "girdle_condition": null, "girdle_thickness_from": "Slightly Thin", "girdle_thickness_to": null, "grading_certificates": [ { "filename": "demo_polished_1.pdf", "description": null, "hash": "1a9cbfaed6dc9fa95203a02dc3ba6ff5939a0e02ad2f433e63f3a24eaf1a0dc4", "grading_lab": "GIA", "graded_date": "0001-01-01T00:00:00", "grader_certificate_no": "GIA 215292022", "grader_report_no": "215292022", "grader_inscription_no": "GIA 215292022" } ], "length": 6.86, "model": null, "pavillion_angle": 40.8, "pavillion_percent": null, "polish_quality": "EX", "plan": null, "plan_reports": null, "quality": null, "scan": { "filename": "demo_polished_1.stl", "description": null, "hash": "bdc971ad48b3d50e93a6796af94391921e8032c62e5850f782c7cf7a60714173", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null }, "scan_reports": [ { "filename": "demo_polished_1.xml", "description": null, "hash": "61dec403d00e715e0d3bd8593f9c4b23635943d1ee16113b3d6f8f6fee9e18f3", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null } ], "shape": "Round", "silhouettes": null, "symmetry": "VG", "table_percent": 57.0, "supplementary_files": null, "width": 6.85, "images": [ { "filename": "demo_polished_1.jpg", "description": "Polished Diamond Picture", "hash": "092aa374cec6e846874ba5bdabc2cf03ad3002eaccc55e0eb8b61697763238b0", "image_type": "default" }, { "filename": "demo_polished_1_Arrows.jpg", "description": "Polished Diamond Picture", "hash": "8eefc0aac8a7ab1b723b207c1984e8d36e4aee5f1df33b7289a480eb6339cf10", "image_type": "arrow" }, { "filename": "demo_polished_1_heart.jpg", "description": "Polished Diamond Picture", "hash": "602a3a79417a7502936ddbbb9b5384f7f65f26ab70ca91f1a0ed7d3961e001b4", "image_type": "heart" } ], "videos": [ { "filename": "demo_polished_1.mp4", "description": "Polished Diamond videos", "hash": "515756198048fad606e270521e6f5b09a17e20ef4240ebfb0ac582f715179f1f" } ] } } ], "clitz8x970000m7yt0pu8u74e": [ { "diamond_id": "clitz8x970000m7yt0pu8u74e", "diamond_parent_id": null, "lifecycle_state": "polished", "current_stage": "polished", "assurance_level": "assured", "provenance": { "provenance_name": "DTC", "provenance_type": "Entity", "mine_name": null }, "rough": { "carats": 5.0, "colour": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": null, "fluorescence_intensity": null, "images": null, "model": null, "plan": null, "plan_reports": null, "quality": null, "scan": null, "scan_reports": null, "silhouettes": null, "stress": null, "supplementary_files": null, "videos": null }, "polished": { "carats": 3.386, "clarity": "VVS2", "colour": "D", "crown_angle": null, "crown_height": null, "culet_condition": null, "culet_size": null, "cut_grade": "VG", "depth": 4.28, "depth_percent": 62.1, "diameter_maximum": null, "diameter_minimum": null, "fancy_colour": null, "fancy_colour_intensity": null, "fancy_colour_overtone": null, "fluorescence_colour": "N", "fluorescence_intensity": null, "girdle_condition": null, "girdle_thickness_from": "Slightly Thin", "girdle_thickness_to": null, "grading_certificates": [ { "filename": "demo_polished_1.pdf", "description": null, "hash": "1a9cbfaed6dc9fa95203a02dc3ba6ff5939a0e02ad2f433e63f3a24eaf1a0dc4", "grading_lab": "GIA", "graded_date": "0001-01-01T00:00:00", "grader_certificate_no": "GIA 215294850", "grader_report_no": "215294850", "grader_inscription_no": "GIA 215294850" } ], "length": 6.83, "model": null, "pavillion_angle": 40.8, "pavillion_percent": null, "polish_quality": "EX", "plan": null, "plan_reports": null, "quality": null, "scan": { "filename": "demo_polished_1.stl", "description": null, "hash": "bdc971ad48b3d50e93a6796af94391921e8032c62e5850f782c7cf7a60714173", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null }, "scan_reports": [ { "filename": "demo_polished_1.xml", "description": null, "hash": "61dec403d00e715e0d3bd8593f9c4b23635943d1ee16113b3d6f8f6fee9e18f3", "scan_device_manufacturer": null, "scan_device_model": null, "scan_software_name": null, "scan_software_version": null } ], "shape": "Round", "silhouettes": null, "symmetry": "VG", "table_percent": 57.0, "supplementary_files": null, "width": 6.85, "images": [ { "filename": "demo_polished_1.jpg", "description": "Polished Diamond Picture", "hash": "092aa374cec6e846874ba5bdabc2cf03ad3002eaccc55e0eb8b61697763238b0", "image_type": "default" }, { "filename": "demo_polished_1_Arrows.jpg", "description": "Polished Diamond Picture", "hash": "8eefc0aac8a7ab1b723b207c1984e8d36e4aee5f1df33b7289a480eb6339cf10", "image_type": "arrow" }, { "filename": "demo_polished_1_heart.jpg", "description": "Polished Diamond Picture", "hash": "602a3a79417a7502936ddbbb9b5384f7f65f26ab70ca91f1a0ed7d3961e001b4", "image_type": "heart" } ], "videos": [ { "filename": "demo_polished_1.mp4", "description": "Polished Diamond videos", "hash": "515756198048fad606e270521e6f5b09a17e20ef4240ebfb0ac582f715179f1f" } ] } } ] } } ] } ``` {% endtab %} {% endtabs %} ### Request The request object is a collection of search items. Each search item is related to a platform ID and a list of Tracr IDs. Example: ```json { "data": [ { "diamonds": [], "platform_id": "platform_id_1", "modified_since": "" }, { "diamonds": [], "platform_id": "platform_id_2", "modified_since": "" } ] } ``` * Diamonds – A list of Tracr IDs from the given platform IDs. * Platform ID - The unique Tracr identifier of the participant. This ID is static. * Modified Since - An optional filter to retrieve only diamonds updated after a specific date. ### Results An array of Result items. *Result item* * Status - The status of the query for the platform. Status can be `success` or `unauthorised`. * Platform ID - The unique Tracr identifier of the participant. * Results - A dictionary with the search results.\ Key : Tracr ID\ Value : A collection of diamonds including ancestors. ### Unauthorised access Each participant needs to authorise the API to access the inventory. If the permission is missing, the API cannot request any diamonds for a platform id. Example: ```json { "status": "unauthorised", "platform_id": "11111111-1111-1111-1111-111111111111", "error": "You are not authorised to request diamonds from this participant." } ``` The participant needs to raise a ticket with Tracr Support () to get the permission set up. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tracr.com/api-reference/get-started-with-tracr-search-bulk.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.