Trial Matcher - Get Job

Reference

Service:: Cognitive Services

API Version:: 2023-09-01-preview

Get Trial Matcher job details
Gets the status and details of the Trial Matcher job.

GET {endpoint}/health-insights/trial-matcher/jobs/{id}?api-version=2023-09-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string uri	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).
id	path	True	string uuid	A processing job identifier.
api-version	query	True	string	The API version to use for this operation.

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Responses

Name	Type	Description
200 OK	TrialMatcherResult	The request has succeeded. Headers Retry-After: integer
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

TrialMatcherResult

The request has succeeded.

Headers

Retry-After: integer

Other Status Codes

Azure.Core.Foundations.ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Gets the status and details of the Trial Matcher job.

Sample request

HTTP

GET {endpoint}/health-insights/trial-matcher/jobs/a4d3d73e-2be3-4ca1-bd4f-66a5bdd19754?api-version=2023-09-01-preview

Sample response

Status code:: 200

{
  "id": "a4d3d73e-2be3-4ca1-bd4f-66a5bdd19754",
  "createdDateTime": "2021-11-28T09:13:11.046Z",
  "expirationDateTime": "2021-11-28T09:13:11.046Z",
  "lastUpdateDateTime": "2021-11-28T09:13:11.046Z",
  "status": "succeeded",
  "result": {
    "patientResults": [
      {
        "patientId": "Patient ID Example 2",
        "inferences": [
          {
            "type": "trialEligibility",
            "value": "Eligible",
            "description": "SwEaTB - Diagnosing of Acute Tuberculosis",
            "confidenceScore": 1,
            "evidence": [
              {
                "eligibilityCriteriaEvidence": "In-patients with acute tuberculosis",
                "patientInfoEvidence": {
                  "system": "UMLS",
                  "code": "C0019046",
                  "name": "tuberculosis"
                },
                "importance": 1
              }
            ],
            "clinicalTrialId": "NCT03667742",
            "source": "clinicaltrials.gov",
            "metadata": {
              "phases": [
                "phase3"
              ],
              "studyType": "observational",
              "recruitmentStatus": "recruiting",
              "conditions": [
                "Tuberculosis"
              ],
              "sponsors": [
                "University Hospital, Basel, Switzerland"
              ],
              "contacts": [
                {
                  "name": "John Doe, PD Dr. Med",
                  "email": "John@contoso.com",
                  "phone": "+55-555-5555-55"
                }
              ],
              "facilities": [
                {
                  "name": "University Hospital, Basel",
                  "city": "Basel",
                  "countryOrRegion": "Switzerland"
                }
              ]
            }
          },
          {
            "type": "trialEligibility",
            "value": "Ineligible",
            "description": "Design of an Integrative Algorithm for Staging Tuberculosis (STAGE-TB)",
            "confidenceScore": 1,
            "evidence": [
              {
                "eligibilityCriteriaEvidence": "negative for Quantiferon- TB Gold Plus Test or ELISpot",
                "patientInfoEvidence": {
                  "system": "UMLS",
                  "code": "C0920508",
                  "name": "Enzyme-Linked Immunospot Assay",
                  "value": "30,000 PBMC cells per 10ul"
                },
                "importance": 1
              }
            ],
            "clinicalTrialId": "NCT03691883",
            "source": "clinicaltrials.gov"
          }
        ],
        "neededClinicalInfo": [
          {
            "system": "UMLS",
            "code": "C4317078",
            "name": "Mycobacterium Tuberculosis Measurement ",
            "semanticType": "Laboratory Procedure",
            "category": "EXAMINATION_NAME"
          },
          {
            "system": "UMLS",
            "code": "C0008031",
            "name": "Chest Pain",
            "semanticType": "Sign or Symptom",
            "category": "SYMPTOM_OR_SIGN"
          }
        ]
      }
    ],
    "modelVersion": "2021-10-28",
    "knowledgeGraphLastUpdateDate": "2021-11-26"
  }
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
ClinicalCodedElement	A piece of clinical information, expressed as a code in a clinical coding system.
ClinicalNoteEvidence	A piece of evidence from a clinical note (text document).
ClinicalTrialMetadata	Trial data which is of interest to the potential participant.
ClinicalTrialPhase	Possible phases of a clinical trial.
ClinicalTrialRecruitmentStatus	Possible recruitment status of a clinical trial.
ClinicalTrialResearchFacility	Details of a research facility where a clinical trial is conducted.
ClinicalTrialSource	Possible sources of a clinical trial.
ClinicalTrialStudyType	Possible study types of a clinical trial.
ContactDetails	A person's contact details.
ExtendedClinicalCodedElement	A piece of clinical information, expressed as a code in a clinical coding system, extended by semantic information.
JobStatus	The status of the processing job.
TrialMatcherInference	An inference made by the Trial Matcher model regarding a patient.
TrialMatcherInferenceEvidence	A piece of evidence corresponding to a Trial Matcher inference.
TrialMatcherInferenceResult	The inference results for the Trial Matcher request.
TrialMatcherInferenceType	The type of the Trial Matcher inference.
TrialMatcherPatientResult	The results of the model's work for a single patient.
TrialMatcherResult	The response for the Trial Matcher request.

Azure.Core.Foundations.Error

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

ClinicalCodedElement

A piece of clinical information, expressed as a code in a clinical coding system.

Name	Type	Description
code	string	The code within the given clinical coding system.
name	string	The name of this coded concept in the coding system.
system	string	The clinical coding system, e.g. ICD-10, SNOMED-CT, UMLS.
value	string	A value associated with the code within the given clinical coding system.

ClinicalNoteEvidence

A piece of evidence from a clinical note (text document).

Name	Type	Description
id	string	The identifier of the document containing the evidence.
length	integer	The length of the evidence text span.
offset	integer	The start index of the evidence text span in the document (0 based).
text	string	The actual text span which is evidence for the inference.

ClinicalTrialMetadata

Trial data which is of interest to the potential participant.

Name	Type	Description
conditions	string[]	Medical conditions and their synonyms which are relevant for the clinical trial, given as strings.
contacts	ContactDetails[]	Contact details of the trial administrators, for patients that want to participate in the trial.
facilities	ClinicalTrialResearchFacility[]	Research facilities where the clinical trial is conducted.
phases	ClinicalTrialPhase[]	Phases which are relevant for the clinical trial. Each clinical trial can be in a certain phase or in multiple phases.
recruitmentStatus	ClinicalTrialRecruitmentStatus	Possible recruitment status of a clinical trial.
sponsors	string[]	Sponsors/collaborators involved with the trial.
studyType	ClinicalTrialStudyType	Possible study types of a clinical trial.

ClinicalTrialPhase

Possible phases of a clinical trial.

Name	Type	Description
earlyPhase1	string
notApplicable	string
phase1	string
phase2	string
phase3	string
phase4	string

ClinicalTrialRecruitmentStatus

Possible recruitment status of a clinical trial.

Name	Type	Description
enrollingByInvitation	string
notYetRecruiting	string
recruiting	string
unknownStatus	string

ClinicalTrialResearchFacility

Details of a research facility where a clinical trial is conducted.

Name	Type	Description
city	string	City name.
countryOrRegion	string	Country/region name.
name	string	The facility's name.
state	string	State name.

ClinicalTrialSource

Possible sources of a clinical trial.

Name	Type	Description
clinicaltrials.gov	string
custom	string

ClinicalTrialStudyType

Possible study types of a clinical trial.

Name	Type	Description
expandedAccess	string
interventional	string
observational	string
patientRegistries	string

ContactDetails

A person's contact details.

Name	Type	Description
email	string	The person's email.
name	string	The person's name.
phone	string	A person's phone number.

ExtendedClinicalCodedElement

A piece of clinical information, expressed as a code in a clinical coding system, extended by semantic information.

Name	Type	Description
category	string	The bio-medical category related to the coded concept, e.g. Diagnosis, Symptom, Medication, Examination.
code	string	The code within the given clinical coding system.
name	string	The name of this coded concept in the coding system.
semanticType	string	The UMLS semantic type associated with the coded concept.
system	string	The clinical coding system, e.g. ICD-10, SNOMED-CT, UMLS.
value	string	A value associated with the code within the given clinical coding system.

JobStatus

The status of the processing job.

Name	Type	Description
canceled	string
failed	string
notStarted	string
running	string
succeeded	string

TrialMatcherInference

An inference made by the Trial Matcher model regarding a patient.

Name	Type	Description
clinicalTrialId	string	The identifier of the clinical trial.
confidenceScore	number	Confidence score for this inference.
description	string	The description corresponding to the inference value.
evidence	TrialMatcherInferenceEvidence[]	The evidence corresponding to the inference value.
metadata	ClinicalTrialMetadata	Trial data which is of interest to the potential participant.
source	ClinicalTrialSource	Possible sources of a clinical trial.
type	TrialMatcherInferenceType	The type of the Trial Matcher inference.
value	string	The value of the inference, as relevant for the given inference type.

TrialMatcherInferenceEvidence

A piece of evidence corresponding to a Trial Matcher inference.

Name	Type	Description
eligibilityCriteriaEvidence	string	A piece of evidence from the eligibility criteria text of a clinical trial.
importance	number	A value indicating how important this piece of evidence is for the inference.
patientDataEvidence	ClinicalNoteEvidence	A piece of evidence from a clinical note (text document).
patientInfoEvidence	ClinicalCodedElement	A piece of clinical information, expressed as a code in a clinical coding system.

TrialMatcherInferenceResult

The inference results for the Trial Matcher request.

Name	Type	Description
knowledgeGraphLastUpdateDate	string	The date when the clinical trials knowledge graph was last updated.
modelVersion	string	The version of the model used for inference, expressed as the model date.
patientResults	TrialMatcherPatientResult[]	Results for the patients given in the request.

TrialMatcherInferenceType

The type of the Trial Matcher inference.

Name	Type	Description
trialEligibility	string

TrialMatcherPatientResult

The results of the model's work for a single patient.

Name	Type	Description
inferences	TrialMatcherInference[]	The inference results for the patient.
neededClinicalInfo	ExtendedClinicalCodedElement[]	Clinical information which is needed to provide better trial matching results for the patient.
patientId	string	The identifier given for the patient in the request.

TrialMatcherResult

The response for the Trial Matcher request.

Name	Type	Description
createdDateTime	string	The date and time when the processing job was created.
error	Azure.Core.Foundations.Error	Error object that describes the error when status is "Failed".
expirationDateTime	string	The date and time when the processing job is set to expire.
id	string	The unique ID of the operation.
lastUpdateDateTime	string	The date and time when the processing job was last updated.
result	TrialMatcherInferenceResult	The result of the operation.
status	JobStatus	The status of the operation

Share via

Trial Matcher - Get Job

URI Parameters

Request Header

Responses

Security

Ocp-Apim-Subscription-Key

Examples

Gets the status and details of the Trial Matcher job.

Sample request

Sample response

Definitions

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

ClinicalCodedElement

ClinicalNoteEvidence

ClinicalTrialMetadata

ClinicalTrialPhase

ClinicalTrialRecruitmentStatus

ClinicalTrialResearchFacility

ClinicalTrialSource

ClinicalTrialStudyType

ContactDetails

ExtendedClinicalCodedElement

JobStatus

TrialMatcherInference

TrialMatcherInferenceEvidence

TrialMatcherInferenceResult

TrialMatcherInferenceType

TrialMatcherPatientResult

TrialMatcherResult

Additional resources