> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parcha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Job by ID

> Retrieve detailed information about a specific job

This endpoint retrieves detailed information about a job by its ID, including its status, progress, and associated check results.

## API Endpoint

```

GET https://api.parcha.ai/api/v1/getJobById
```

## Query Parameters

<ParamField query="job_id" type="string" required>
  The unique identifier of the job to retrieve.
</ParamField>

<ParamField query="include_check_result_ids" type="boolean" default="false">
  If true, includes only the IDs of check results. Cannot be used with `include_check_results`.
</ParamField>

<ParamField query="include_check_results" type="boolean" default="false">
  If true, includes full check result objects. Cannot be used with `include_check_result_ids`.
</ParamField>

<ParamField query="include_status_messages" type="boolean" default="false">
  If true, includes status messages associated with the job.
</ParamField>

<ParamField query="jsonpath_query" type="string">
  Optional JSONPath query to filter and extract specific fields from the response. Useful for reducing payload size when `include_check_results=true` returns large amounts of data.
  See [Filtering Check Results](#filtering-check-results) below for examples.
</ParamField>

## Filtering Check Results

When using `include_check_results=true`, the response can contain large amounts of data. Use the `jsonpath_query` parameter to filter and extract only the data you need.

### JSONPath Syntax

The API uses [JSONPath](https://goessner.net/articles/JsonPath/) syntax for filtering. Here are common patterns:

* **Filter by field value**: `$.check_results[?(@.field=='value')]`
* **Get all items**: `$.check_results[*]`
* **Extract specific field**: `$.check_results[*].field_name`
* **Nested field access**: `$.check_results[*].payload.nested_field`

### Common Use Cases

<AccordionGroup>
  <Accordion title="Filter by specific check (command_id)">
    Get only the results for a specific check type:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array containing only the web presence check result
  </Accordion>

  <Accordion title="Get only failed checks">
    Filter to see only checks that didn't pass:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.passed==false)]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of failed check results
  </Accordion>

  <Accordion title="Extract specific payload fields">
    Get just the payload type from all check results:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[*].payload.type' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of payload type strings (e.g., `["WebPresenceCheckResult", "PolicyCheckResult"]`)
  </Accordion>

  <Accordion title="Get nested array data">
    Extract specific nested fields from check result payloads:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.web_presence_check")].payload.verified_hits[*].hit_name' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of hit names from the verified\_hits array (e.g., `["LinkedIn", "Crunchbase"]`)
  </Accordion>

  <Accordion title="Filter by check status">
    Get all completed checks:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.status=="complete")]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of completed check results
  </Accordion>
</AccordionGroup>

### Adverse Media Filtering Examples

For detailed adverse media structure, see the [Adverse Media Screening Check documentation](/api-reference/check-results/adverse-media-screening-check).

<AccordionGroup>
  <Accordion title="Get all adverse media articles">
    Retrieve all verified adverse media hits for a job:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of all adverse media profiles found
  </Accordion>

  <Accordion title="Get only articles where business is the perpetrator">
    Filter for articles where the business is identified as the perpetrator:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.is_perpetrator==true)]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of weblinks where `is_perpetrator` is `true`
  </Accordion>

  <Accordion title="Get articles from specific sources">
    Filter for articles from Google Search only:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.article_source=="serp_google_search")]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of weblinks from Google Search

    **Other sources**: `refinitiv_world_check`, `comply_advantage`, `serp_google_news`, `serp_brave_search`
  </Accordion>

  <Accordion title="Get articles about specific topics">
    Filter for articles about regulatory violations:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("Regulatory Violations" in @.metadata.topics)]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of weblinks with "Regulatory Violations" in topics

    **Common topics**: "Legal Disputes", "Compliance Issues", "Safety Issues", "Financial Misconduct", "Criminal Activity"
  </Accordion>

  <Accordion title="Get article titles and URLs only">
    Extract just the article titles and URLs:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*][title,url]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of objects with only `title` and `url` fields
  </Accordion>

  <Accordion title="Get articles from recent years">
    Filter for articles published in 2024 or later:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?(@.metadata.year_of_article_publication>=2024)]' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of weblinks published in 2024 or later
  </Accordion>

  <Accordion title="Get article summaries by country">
    Get summaries for articles from a specific country:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[?("United States" in @.where_countries)].metadata.summary_of_event' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of event summaries for articles from the United States
  </Accordion>

  <Accordion title="Get direct quotes from articles">
    Extract all direct quotes about the business:

    ```bash theme={null}
    curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=YOUR_JOB_ID&include_check_results=true&jsonpath_query=$.check_results[?(@.command_id=="kyb.adverse_media_screening_check_v2")].payload.verified_adverse_media_hits[*].weblinks[*].metadata.quote_from_article' \
    -H 'Authorization: Bearer YOUR_API_KEY'
    ```

    **Returns**: Array of direct quotes from adverse media articles
  </Accordion>
</AccordionGroup>

### Python Example

```python theme={null}
import requests
from urllib.parse import quote

api_key = 'YOUR_API_KEY'
job_id = '123e4567-e89b-12d3-a456-426614174000'

# Filter for failed checks
jsonpath_query = '$.check_results[?(@.passed==false)]'
url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true&jsonpath_query={quote(jsonpath_query)}'

headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get(url, headers=headers)

# Response contains only failed checks
failed_checks = response.json()
print(f"Found {len(failed_checks)} failed checks")
```

### Error Handling

<ResponseField name="400 Bad Request" type="object">
  Returned when the JSONPath query has invalid syntax.

  <Expandable title="Example Error">
    ```json theme={null}
    {
      "error": "Invalid JSONPath query: Error on line 1, col 16: Unexpected character: ?"
    }
    ```
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found" type="object">
  Returned when the JSONPath query returns no results.

  <Expandable title="Example Error">
    ```json theme={null}
    {
      "error": "JSONPath query returned no results"
    }
    ```
  </Expandable>
</ResponseField>

<Note>
  **JSONPath Resources**:

  * [JSONPath Online Evaluator](https://jsonpath.com/) - Test your queries
  * [JSONPath Documentation](https://goessner.net/articles/JsonPath/) - Full syntax reference
  * The API uses the [jsonpath-ng](https://github.com/h2non/jsonpath-ng) library with extended filter support
</Note>

## Response

<ResponseField name="id" type="string">
  The unique identifier for the job.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The ID of the agent that executed the job.
</ResponseField>

<ResponseField name="owner_id" type="string">
  The email address of the job owner.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the job (e.g., PENDING, RUNNING, COMPLETED, FAILED, RETRIED).
  If the status is `RETRIED`, it means this job instance was superseded by a new job. You should use the `new_job_id` to fetch the latest job information.
</ResponseField>

<ResponseField name="started_at" type="string">
  The timestamp when the job started.
</ResponseField>

<ResponseField name="completed_at" type="string">
  The timestamp when the job completed.
</ResponseField>

<ResponseField name="recommendation" type="string">
  The recommendation based on the job results.
</ResponseField>

<ResponseField name="input_payload" type="object">
  The input data provided for the job.
</ResponseField>

<ResponseField name="status_messages" type="array">
  An array of status messages associated with the job.
</ResponseField>

<ResponseField name="new_job_id" type="string">
  The unique identifier of the new job that was created as a retry of this job. This field is present only if the `status` is `RETRIED`.
</ResponseField>

<ResponseField name="original_job_id" type="string">
  The unique identifier of the original job that this job is a retry of. This field is present if this job was created as a retry of a previous job.
</ResponseField>

<ResponseField name="check_results" type="array">
  An array of check results from the job execution.

  <Expandable title="Check Result Example">
    ```json theme={null}
    {
      "step_description": "Tool used to determine if the business profile provided by the business matches the verified business profile",
      "name": "KYB Basic Business Profile Check",
      "instruction": "Generate and validate a basic business profile from web data and check against self attested data.",
      "command_result": {
        "agent_key": "your-kyb-agent-key",
        "command_id": "kyb.basic_business_profile_check",
        "command_name": "KYB Basic Business Profile Check",
        "command_desc": "Tool used to determine if the business profile provided by the business matches the verified business profile",
        "command_instance_id": "a5494583409b41d587cd753b686bcf43",
        "output": {
          "explanation": "This task involves verifying the accuracy of self-reported business information against verified data sources. The goal is to ensure that the self-reported business profile aligns with the information verified from reliable sources.",
          "payload": {
            "type": "BasicBusinessProfileCheckResult",
            "business_name_match": {
              "exact_match": true,
              "partial_match": false,
              "source_ids": [
                "fxvqri"
              ],
              "explanation": "The business name 'Parcha' exactly matches the name found in the verified data.",
              "name": "Parcha"
            },
            "business_description_match": null,
            "business_industry_match": null
          },
          "answer": "The basic business profile check passed. The self-reported business name 'Parcha' matches the verified data, and no discrepancies were found as other fields were not provided in the self-reported data.",
          "passed": true,
          "recommendation": null,
          "alerts": {}
        },
        "agent_instance_id": "09e3133959c447b493313b1b3360cc05"
      },
      "on_check_failure": null
    }
    ```
  </Expandable>
</ResponseField>

## Usage Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=123e4567-e89b-12d3-a456-426614174000&include_check_results=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  api_key = 'YOUR_API_KEY'
  job_id = '123e4567-e89b-12d3-a456-426614174000'
  url = f'https://api.parcha.ai/api/v1/getJobById?job_id={job_id}&include_check_results=true'

  headers = {
      'Authorization': f'Bearer {api_key}'
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  import axios from 'axios';

  const apiKey = 'YOUR_API_KEY';
  const jobId = '123e4567-e89b-12d3-a456-426614174000';
  const url = `https://api.parcha.ai/api/v1/getJobById?job_id=${jobId}&include_check_results=true`;

  axios.get(url, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  })
  .then(response => console.log(response.data))
  .catch(error => console.error('Error:', error));
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
    "created_at": "2024-09-06T03:06:57.213129",
    "id": "50432480-5ab8-433c-b7be-a0e40408029a",
    "agent_id": "your-agent-key",
    "descope_user_id": "U2U2iomFdkpU6FcNgU8wmEtkvnde",
    "started_at": "2024-09-06T03:06:57.645676",
    "progress": null,
    "queued_at": null,
    "tenant_id": "T2QyrSQP8m6UOfLLqTux2q0Gj5AW",
    "updated_at": "2024-09-06T03:06:57.213133",
    "celery_task_id": null,
    "owner_id": "miguel@parcha.ai",
    "status": "RETRIED",
    "new_job_id": "60532481-6bc9-444d-c8cf-b1f50509030b",
    "original_job_id": null,
    "completed_at": "2024-09-06T03:13:07.371114",
    "recommendation": "Review",
    "input_payload": {
        "id": "parcha-5f7008a3",
        "self_attested_data": {
            "type": "SelfAttestedData",
            "website": "https://parcha.ai"
        },
        "research_data": {
            "type": "WebResearchDataCheck",
            "data": {
                "type": "WebResearchData",
                "is_valid_url": false,
                "is_filtered": false
            }
        },
        "self_attested_address_check": {
            "type": "SelfAttestedAddressCheck",
            "result": {
                "type": "SelfAttestedAddressCheckResult",
                "operating_address_verified": false,
                "operating_address_is_business": false,
                "operating_address_is_pobox": false,
                "operating_address_is_residential": false
            }
        },
        "web_presence_check": {
            "type": "WebPresenceCheck",
            "data": {
                "type": "WebPresenceCheckData",
                "only_used_search_results": false,
                "only_used_self_attested_websites": false,
                "only_used_extended_search_results": false
            }
        },
        "mcc_code_check": {
            "type": "MCCCodeCheck",
            "result": {
                "type": "MCCCodeCheckResult",
                "mcc_code_description": "No description found."
            }
        }
    },
    "status_messages": [],
    "check_results": [
        {
            "job_id": "50432480-5ab8-433c-b7be-a0e40408029a",
            "command_desc": "Tool to determine if the web presence data loader succeeded.",
            "step_number": null,
            "updated_at": "2024-09-06T03:08:57.865904",
            "result_type": "CommandResult",
            "status": "complete",
            "created_at": "2024-09-06T03:06:58.149768",
            "input_data": {
                "business_name": "Parcha",
                "business_description": null
            },
            "verification_data": {
                "type": "WebPresenceCheckData",
                "self_attested_webpages": [
                    // ... (webpage data omitted for brevity)
                ]
            },
            // ... (other check results omitted for brevity)
        }
    ]
}
```

## Notes

<Note>
  The `include_check_result_ids` and `include_check_results` parameters are mutually exclusive. Using both will result in a 400 Bad Request error.
</Note>

<Warning>
  Access to job details is restricted. The API will return a 401 Unauthorized error if the user doesn't have access to the specified agent.
</Warning>

<Info>
  If the job is not found, a 404 Not Found error will be returned.
</Info>

This endpoint provides a comprehensive view of a job's status and results, allowing for detailed tracking and analysis of the KYB/KYC process.

## Error Responses

<ResponseField name="400 Bad Request" type="object">
  <ResponseField name="error" type="string">
    "Cannot include both check result ids and check results in the response"
  </ResponseField>
</ResponseField>

<ResponseField name="401 Unauthorized" type="object">
  <ResponseField name="error" type="string">
    "Unauthorized"
  </ResponseField>
</ResponseField>

<ResponseField name="404 Not Found" type="object">
  <ResponseField name="error" type="string">
    "Job not found"
  </ResponseField>
</ResponseField>


## OpenAPI

````yaml GET /getJobById
openapi: 3.0.0
info:
  title: Parcha API
  version: 1.0.0
  description: API for managing Parcha jobs and checks
servers:
  - url: https://api.parcha.ai/api/v1
    description: Agent Hub API server
  - url: https://demo.parcha.ai/api/v1
    description: Sandbox API server
  - url: https://us1.parcha.ai/api/v1
    description: Legacy API server
  - url: http://{your-company-domain}.parcha.ai/api/v1
    description: Custom Enterpris server (your company's API server)
security:
  - bearerAuth: []
paths:
  /getJobById:
    get:
      summary: Get job by ID
      parameters:
        - name: job_id
          in: query
          required: true
          schema:
            type: string
        - name: include_check_result_ids
          in: query
          schema:
            type: boolean
        - name: include_check_results
          in: query
          schema:
            type: boolean
        - name: include_status_messages
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Job retrieved successfully
        '401':
          description: Unauthorized
        '404':
          description: Job not found
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key obtained from your Parcha account settings. Include as Bearer
        token in the Authorization header.

````