---
title: "Search for custom objects by a given filter"
method: POST
path: "/custom-objects/{type}/search"
tags: ["custom-objects"]
---

# Search for custom objects by a given filter

`POST /custom-objects/{type}/search`

Filterable fields and their allowed operators:

 Field | Allowed operators |
 --- | --- |
 `name` | `equals`, `in`, `not_in`, `string_contains`, `string_does_not_contain`, `is_set`, `is_unset` |
 `created_at` | `time_is_after`, `time_is_before`, `time_range` |
 `updated_at` | `time_is_after`, `time_is_before`, `time_range` |

Timestamp values use RFC3339 format. For custom fields, pass the field slug as `field`.

**Rate limit:** 120 requests per minute

## Path parameters

- `type` string, required

## Request body

- SearchCustomObjectsRequest
  - `cursor` string — The cursor to use for pagination.
  - `filter` Filter
    - `field` string — The field for this filter. For allowed fields, see the documentation for the specific endpoint you are using. For non-compound filters (any operators other than "and" or "or"), field must be set, along with either value or values, depending on the operator.
    - `operator` 'equals' | 'not_equals' | 'contains' | 'does_not_contain' | 'in' | 'not_in' | 'and' | 'or' | 'time_is_after' | 'time_is_before' | 'time_range' | 'string_contains' | 'string_does_not_contain' | 'is_set' | 'is_unset' | 'greater_than' | 'less_than' | 'greater_than_or_equals' | 'less_than_or_equals', required — The operator for this filter.
    - `subfilters` Filter[] — Sub-filters for this filter. Valid only when operator is "and" or "or". The maximum allowed depth for a tree of filters is 3.
    - `value` string — The value for this filter. Only used for single-valued operators ("equals", "not_equals", "contains", "does_not_contain")
    - `values` string[] — The values for this filter. Only used for multi-valued operators ("in", "not_in").
  - `limit` integer — The number of results to fetch. Defaults to 25, max 100.

## Response `200`

- SearchCustomObjectsResponseBody
  - `data` APICustomObject[]
    - `created_at` string — When the object was created.
    - `custom_fields` object — Custom field values keyed by field slug. Relationship-typed fields are excluded here and returned in the `relations` field instead.
    - `id` string — The ID of the custom object.
    - `name` string — The name of the custom object.
    - `relations` APIObjectRelation[] — Relationships from this object to other objects, sourced from relationship-typed custom fields.
      - `object_id` string — The ID of the related object.
      - `object_type` string — The type of the related object (e.g. "account", "contact", "issue").
    - `type` string — The type slug of the custom object.
    - `updated_at` string — When the object was last updated.
  - `pagination` Pagination
    - `cursor` string, required — The cursor for the next page of results.
    - `has_next_page` boolean, required — Indicates if there is a next page of results.
  - `request_id` string

## Other responses

- `400` — The request was invalid or could not be completed.
- `403` — The authenticated caller or organization is not allowed to access this endpoint or operation.
- `404`
- `500` — An unexpected internal error occurred.

## Changes

> 22 revisions in range; 1 could not be searched.

- **2026-08-28** `fe3adb90ea45` — 1 info
  - added the non-success response with the status `403`
- **2026-08-18** `b387b041ea8e` — 1 info
  - the request property `filter/field` became optional

[Change history](https://skmtc.dev/usepylon/apis/pylon-api/changes/custom-objects/:type/search/post.md)

---

[API](https://skmtc.dev/usepylon/apis/pylon-api.md) · [All operations](https://skmtc.dev/usepylon/apis/pylon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/usepylon/pylon-api/revisions/7b12ab92de27/schema)