

Last date modified: April 15 2025
Search terms reports provide the ability to identify documents containing specific keywords or terms. You can enter multiple terms and generate a report listing the number of hits for each term in a document. For more information, see
The Search Terms Report Services provides functionality for generating a search terms report, adding terms to an existing search terms report, retrying any errors, and viewing the build progress of a specific search terms report.
The following sample use cases illustrate how you can use this service:
You can also use the Search Terms Report Services through .NET. For more information, see Search Terms Report Services (.NET).
Review the following guidelines for working with the Search Terms Report Services.
The URLs for REST endpoints contain path parameters that you need to set before making a call:
For example, you can use the following URL to run a job for a search terms report:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/run-all-terms
Set the path parameters as follows:
To create a search term report, use the Object Manager to create a Search Terms Report Object by sending a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/Relativity.Objects/workspace/<workspaceID>/object/create
Fill in the query parameters for:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
"request":{
"FieldValues":[
{
"Field":{
"Name":"Name"
},
"Value":"test STR created from REST API"
},
{
"Field":{
"Name":"Index"
},
"Value":{
"ArtifactID":1041994
}
},
{
"Field":{
"Name":"Searchable set"
},
"Value":{
"ArtifactID":1038051
}
},
{
"Field":{
"Name":"Include Relational Group"
},
"Value":null
},
{
"Field":{
"Name":"Type"
},
"Value":{
"ArtifactID":1035328
}
},
{
"Field":{
"Name":"Calculate Unique Hits"
},
"Value":false
},
{
"Field":{
"Name":"Email Notification Recipients"
},
"Value":null
},
{
"Field":{
"Name":"Notes"
},
"Value":null
},
{
"Field":{
"Name":"Show In Field Tree"
},
"Value":true
},
{
"Field":{
"Name":"Remove Hidden Characters In Terms"
},
"Value":true
}
],
"ObjectType":{
"Guid":"481E9ACF-368B-4341-B6B5-A21153AD9950"
}
}
}
This call uses Object Manager to create a Search Terms Report Object. Enter values for these fields as indicated below (you can refer to the Relativity User Documentation on creating a Search Terms Report for a detailed description of each field).
The response for the create STR operation is the same as for creating an RDO. See the Create an RDO section of the Object Manager for more details on the response.
To create terms used in a search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/create-terms
1
2
3
4
5
6
7
8
9
{
"createRequest":{
"TermsToAdd":[
"term1",
"term2"
],
"RelativityHighlightColor":"5;16"
}
}
1
2
3
4
5
6
{
"TermsAffected":2,
"TermsSkippedAsDuplicates":0,
"TermsSkippedForLength":0,
"TermsSkippedAsErrors":0
}
To modify existing terms used in a search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/update-terms
The body of a request must contain an updateRequest object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"updateRequest":{
"UpdatedTerms":[
{
"ArtifactID":123123,
"NewTerm":"termX"
},
{
"ArtifactID":321321,
"NewTerm":"termY"
}
],
"RelativityHighlightColor":"5;16"
}
}
The response for an update operation contains the same fields as those for a create response. See the field descriptions and JSON sample for the response in Create response field descriptions.
To queue a Run All Terms job for a search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/run-all-terms
The request body is empty.
The body of the response is empty. The service returns one of the following HTTP status codes:
Status | Description |
---|---|
200 | Success |
404 | Invalid Workspace ID |
500 | Invalid Search Terms Report ID |
To queue a Run Pending Terms job for a search terms report, send a POST request with a URL in the following format:
1
<host>Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/run-pending-terms
The request body is empty.
The body of the response is empty. The service returns one of the following HTTP status codes:
Status | Description |
---|---|
200 | Success |
404 | Invalid Workspace ID |
500 | Invalid Search Terms Report ID |
To view the build progress of a search terms report and related statistics, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/get-progress
The request body is empty.
1
2
3
4
5
6
7
8
9
10
11
{
"TermsCompleted":17,
"TermsPending":93,
"TermsError":0,
"TermsNew":13,
"TermsTotal":123,
"TotalDocumentsWithHits":1337,
"TotalDocumentsWithHitsIncludingGroup":0,
"DocumentsInSearchableSet":2000,
"TimeElapsedInSeconds":234"Status":"Processing""JobType":"Run All Terms"
}
To queue a Retry Errors job for a search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/retry-errors
The request body is empty.
The body of the response is empty. The service returns one of the following HTTP status codes:
Status | Description |
---|---|
200 | Success |
404 | Invalid Workspace ID |
500 | Invalid Search Terms Report ID |
To cancel a running search terms report job, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/cancel-job
The request body is empty.
The body of the response is empty. The service returns one of the following HTTP status codes:
Status | Description |
---|---|
200 | Success |
404 | Invalid Workspace ID |
500 | Invalid Search Terms Report ID |
To retrieve the URL used for navigating to the Search Terms Result tab with the appropriate filter criteria for this search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/get-results-url
The request body is empty.
The response body contains the URL string.
To retrieve the URL used to navigate to a search terms report, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/SearchTermsReport/{searchTermsReportID}/get-report-url
The request body is empty.
The response body contains the URL string.
To check whether a search index contains at least one long text field, send a GET request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/indexID/{indexID}/index-contains-long-text-field
The {indexID} path parameter is the Artifact ID of a search index.
The request body is empty.
The response body contains a Boolean value.
To retrieve the object types for the Search Terms Report and Result objects, send a GET request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/get-str-object-types
The request body is empty.
The response contains the following fields:
1
2
3
4
{
"SearchTermsReportObjectTypeID":1000006,
"SearchTermsResultObjectTypeID":1000007
}
To retrieve the report type choice IDs for a workspace, send a GET request with a URL in the following format:
1
<host>/Relativity.REST/api/relativity-search-terms-report/{versionNumber}/workspace/{workspaceID}/get-report-type-ids
The request body is empty.
The response contains the following fields:
1
2
3
4
{
"Report only":1035327,
"Report and tag":1035328
}
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |