# Search metadata

`POST /v1/environments/{environmentId}/logs/search/metadata`

Available as MCP tool `search-metadata` (Read).

Logs endpoints allow you to review log metadata, including relevant timestamps and statuses. Or, if you want to dig into a log for troubleshooting purposes, you can run log inspector. 

> **Log payloads not returned**
>
> You can search log metadata or payloads via API, but you won’t receive log payloads in the responses. You can only review log payload contents in the Redox dashboard (if you’re assigned to an engineer or support role).

You can retrieve a list of log metadata, search for specific data within log payloads, retrieve one log with its metadata, or run log inspector.  

### Search metadata

Search for relevant logs using query parameters to refine the returned list of log metadata. Results are sorted by timestamp, then log ID for logs with matching timestamps. 

When retrieving a large list of logs, use `updatedAfter` and `updatedBefore` to define a date range. This allows for faster, more accurate results.

All users can search log metadata.

## Request parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environmentId` | path | string | Yes | Identifies the specific environment that you're operating in or on behalf of. |
| `_count` | query | number | No | Defines the number of results to return per page. The maximum value per page is 50. |
| `_cursor` | query | string | No | Identifies the next set of results for a given search. |

## Request body

You must include a `requestBody`, even if it's empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `facilityCode` | string | No | Searches the FacilityCode field specified in Redox JSON's Meta header |
| `dataMode` | string | No | Indicates the type of log traffic to search (e.g., `backfill` or `realtime`). Backfill traffic is typically historical data that populates your system prior to go-live with your connection. Real-time traffic is normal traffic that happens between you and your connection after go-live. By default, log searches only query your database for real-time traffic unless you set this parameter to `backfill`. Leaving this parameter blank maintains default behavior. Possible values: realtime, backfill |
| `serviceRegion` | string | No | This field is required if your environment is configured with multiple regions. Possible values: AWS_USA_EAST_1, AWS_CAN_CENTRAL, GCP_USA_CENTRAL_1 |
| `dataModel` | string | No | Indicates the data model used to exchange data.\n\nThis is the equivalent of the `Meta.DataModel` field in our data models. |
| `eventType` | string | No | Indicates the particular event type of a data model that's used to exchange data.\n\nThis is the equivalent of the `Meta.EventType` field in our data models. |
| `createdAfter` | string (date-time) | No | Used to set a date range for the logs to search, which we recommend if you plan to export large amounts of log metadata. This parameter designates that the creation date for the logs to search should be equal to or greater than the date and time in this format (YYYY-MM-DDThh:mm:ss.sssZ). |
| `createdBefore` | string (date-time) | No | Used to set a date range for the logs to search, which we recommend if you plan to export large amounts of log metadata. This parameter designates that the creation date for the logs to search should be less than or equal to the date and time in this format (YYYY-MM-DDThh:mm:ss.sssZ). |
| `updatedAfter` | string (date-time) | No | Used to set a date range for the logs to search, which we recommend if you plan to export large amounts of log metadata. This parameter designates that the last updated date for the logs to search should be equal to or creater than the date and time in this format (YYYY-MM-DDThh:mm:ss.sssZ). |
| `updatedBefore` | string (date-time) | No | Used to set a date range for the logs to search, which we recommend if you plan to export large amounts of log metadata. This parameter designates that the last updated date for the logs to search should be less than or equal to the date and time in this format (YYYY-MM-DDThh:mm:ss.sssZ). |
| `sourceId` | string (uuid) | No | Contains the unique identifier of the source. |
| `destinationId` | string (uuid) | No | Contains the unique identifier of the destination. |
| `type` | string | No | Indicates the type of data exchange that initiated the log (e.g., `send`, `receive`, `request`, `respond`, `unknown`). Possible values: receive, request, respond, send, unknown |
| `status` | string | No | Indicates the current status of the log [e.g., `succeeded`, `failed`, `filtered`, `pending`]. Possible values: failed, filtered, pending, succeeded |

## Request example

_Generated from the schema: the values are placeholders, not a real payload._

```bash
curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/logs/search/metadata' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "facilityCode": "2.16.840.1.113883.3.6147.458",
  "dataMode": "realtime",
  "serviceRegion": "AWS_USA_EAST_1",
  "dataModel": "PatientAdmin",
  "eventType": "Transfer",
  "createdAfter": "2023-01-01T00:00:00.000Z",
  "createdBefore": "2023-01-31T23:59:59.999Z",
  "updatedAfter": "2023-01-01T00:00:00.000Z",
  "updatedBefore": "2023-01-31T23:59:59.999Z",
  "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
  "destinationId": "d0a0ebc7-d6b4-4f3c-a5af-5761a8148e3a",
  "type": "receive",
  "status": "succeeded"
}'
```

## Responses

### 200

Contains a list of metadata for logs matching the query parameter criteria.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meta` | object | No |  |
| `meta.version` | string | No | Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences. |
| `meta.page` | object | No | Contains metadata about paginated results of returned data. |
| `meta.page.links` | object | No |  |
| `meta.page.links.self` | string | No | Links to the current page of results. |
| `meta.page.links.first` | string | No | Links to the first page of results. |
| `meta.page.links.next` | string | No | Links to the next page of results. |
| `meta.page.pageSize` | number | No | Describes the number of records included in each page of the current result set. |
| `meta.page.pageType` | string | No | Describes the pagination algorithm. This endpoint only supports cursor pagination. Value: cursor |
| `meta.totalCount` | integer | No | Contains the total number of logs that match your search criteria across all pages. |
| `payload` | object | No | Contains the query results for each log entry. |
| `payload.results` | Array of object | No |  |
| `payload.results[].id` | string (uuid) | No | Contains the unique identifier of the log. |
| `payload.results[].createdAt` | string (date-time) | No | Displays the date and time that the log was originally created in ISO 8601 format, which is associated with the date and time that the related data exchange took place. |
| `payload.results[].updatedAt` | string (date-time) | No | Displays the date and time when the log was last updated in ISO 8601 format. |
| `payload.results[].dataModel` | string | No | Indicates the data model used to exchange data.\n\nThis is the equivalent of the `Meta.DataModel` field in our data models. |
| `payload.results[].eventType` | string | No | Indicates the particular event type of a data model that's used to exchange data.\n\nThis is the equivalent of the `Meta.EventType` field in our data models. |
| `payload.results[].status` | string | No | Indicates the current status of the log [e.g., `succeeded`, `failed`, `filtered`, `pending`]. Possible values: failed, filtered, pending, succeeded |
| `payload.results[].type` | string | No | Indicates the type of data exchange that initiated the log (e.g., `send`, `receive`, `request`, `respond`, `unknown`). Possible values: receive, request, respond, send, unknown |
| `payload.results[].source` | object | No | Describes the system that initiated the log. |
| `payload.results[].source.id` | string (uuid) | No | Contains the unique identifier of the source. |
| `payload.results[].source.name` | string, nullable | No | Displays the human-readable name of the source. |
| `payload.results[].source.organization` | object | No | Contains metadata about the Redox organization. |
| `payload.results[].source.organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.results[].source.organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.results[].destination` | object | No | Describes the intended destination of the log. |
| `payload.results[].destination.id` | string (uuid) | No | Contains the unique identifier of the destination. |
| `payload.results[].destination.name` | string, nullable | No | Displays the human-readable name of the destination. |
| `payload.results[].destination.organization` | object | No | Contains metadata about the Redox organization. |
| `payload.results[].destination.organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.results[].destination.organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.results[].transactionMetadata` | object | No | Redox-managed field for additional metadata. |

_Generated from the schema: the values are placeholders, not a real payload._

```json
{
  "meta": {
    "version": "1.0.0",
    "page": {
      "links": {
        "self": "string",
        "first": "string",
        "next": "string"
      },
      "pageSize": 0,
      "pageType": "cursor"
    },
    "totalCount": 1250
  },
  "payload": {
    "results": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "createdAt": "2024-02-27T17:50:10.584Z",
        "updatedAt": "2024-02-27T17:50:10.584Z",
        "dataModel": "PatientAdmin",
        "eventType": "Transfer",
        "status": "succeeded",
        "type": "receive",
        "source": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "organization": {
            "id": 122,
            "name": "string"
          }
        },
        "destination": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "organization": {
            "id": 122,
            "name": "string"
          }
        },
        "transactionMetadata": {}
      }
    ]
  }
}
```

### 400

Bad Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.id` | string | No | Contains a unique identifier for the given error instance. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Bad Request`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Bad Request",
      "code": "validation.error.bad.request",
      "detail": "Error details",
      "status": 400,
      "transient": false
    }
  }
}
```

### 403

Forbidden

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.errors` | Array of object | No |  |
| `payload.errors[].title` | string | No | Displays the high-level error message, typically something succinct like `Forbidden`. |
| `payload.errors[].code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |

```json
{
  "payload": {
    "errors": [
      {
        "title": "Forbidden",
        "code": "authorization.forbidden"
      }
    ]
  }
}
```

### 500

Internal Server Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Failed in step X`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Internal Server Error",
      "code": "failed.db.lookup",
      "detail": "Error details",
      "status": 500,
      "transient": true
    }
  }
}
```