Catalogs, jobs, and system tools

search_datahub_catalogs: List the unified catalogs in a project, or fetch one by ID.
search_datahub_jobs: Search the pipeline jobs for a workspace or a project, or poll one job.
get_datahub_system_configuration: Get the built-in system attribute model.

search_datahub_catalogs

Searches the unified catalogs in a project, or fetches one by ID. The result set combines legacy Marketing catalogs with catalogs backed by Data hub, and each record carries five item_collection_* fields showing which item collection sits behind it. Those linkage fields are the reason to use this tool. When item_collection_id is null, the catalog is a legacy one that no item collection manages.

This tool and search_catalogs read the same catalog set, and both are supported. Reach for this one when you need the item collection linkage, and for search_catalogs when you're browsing catalogs generally. For Search catalogs, which live in a separate store with their own fields, use search_discovery_catalogs instead.

Omit catalog_id to list every catalog for the project, or pass it to fetch one catalog along with its full field schema, including which fields are indexed for search. The list endpoint returns the whole set in a single response, so there's no pagination. The project needs the Data hub module enabled, otherwise the request is rejected. Resolve project_id with list_cloud_organizations and then list_projects. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str \| null`	No	A catalog ID from a previous list call. Omit to list all catalogs. Pass it to fetch one catalog with its field schema.

Response parameters

In list mode, when catalog_id is omitted, the tool returns a DataHubCatalogsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[DataHubCatalogSummary]`	The unified catalogs for this project.
`error`	`str \| null`	Error message if the request failed.

The DataHubCatalogSummary object has the following fields:

Field	Type	Description
`id`	`str`	The catalog's unique ID.
`name`	`str`	The machine-readable catalog name.
`display_name`	`str`	The human-readable name. An empty string for `v1` catalogs.
`description`	`str`	The catalog description. An empty string when it isn't set.
`type`	`str`	The catalog type: `generic`, `product`, or `variant`.
`catalog_version`	`str`	The catalog version, `v1` or `v2`.
`company_id`	`str`	The project this catalog belongs to.
`created`	`float \| null`	Unix timestamp of when the catalog was created.
`edited`	`float \| null`	Unix timestamp of the last edit. A `null` value means the catalog was never edited.
`created_by_id`	`str \| null`	The creator's ID. A `null` value is expected for `v1` catalogs created with an API key.
`created_by_display_name`	`str`	The display name of the creator. An empty string when it's unavailable.
`edited_by_id`	`str \| null`	The last editor's ID. A `null` value means the catalog was never edited.
`edited_by_display_name`	`str`	The display name of the last editor. An empty string when it's unavailable.
`last_accessed`	`float`	Unix timestamp of when the catalog was last accessed.
`elastic_last_accessed`	`float`	Unix timestamp of the last Elasticsearch access. `0.0` for new catalogs.
`elastic_backend_closed`	`bool`	Whether the Elasticsearch backend is closed.
`is_product_catalog`	`bool`	Whether this catalog is designated as the project's product catalog.
`searchable_lists_enabled`	`bool`	Whether searchable lists are enabled.
`item_collection_id`	`str \| null`	The Data hub item collection backing this catalog. A `null` value means the catalog is legacy.
`item_collection_name`	`str \| null`	The machine name of the backing item collection. A `null` value means the catalog is legacy.
`item_collection_display_name`	`str \| null`	The display name of the backing item collection, resolved at request time.
`item_collection_scope_type`	`str \| null`	The scope type of the backing item collection, such as `workspace`.
`item_collection_scope_id`	`str \| null`	The scope ID, meaning the workspace ID, of the backing item collection.

In detail mode, when catalog_id is set, the tool returns a DataHubCatalogResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`DataHubCatalog \| null`	The catalog's details, including its field schema.
`error`	`str \| null`	Error message if the request failed.

The DataHubCatalog object has every field of DataHubCatalogSummary, plus:

Field	Type	Description
`fields`	`list[CatalogField]`	The catalog field schema. An empty list when no fields are defined.

The CatalogField object has the following fields:

Field	Type	Description
`name`	`str`	The field name.
`type`	`str`	The field type: `string`, `number`, or `boolean`.
`searchable`	`bool`	Whether the field is indexed for search.

search_datahub_jobs

Searches the asynchronous pipeline jobs behind Data hub, or polls a single job by ID. Jobs are the work items that move product data through the platform: records-update writes raw records, items-update transforms them, configuration-update applies schema changes, and discovery-search-update pushes to the search index. This is where you look when a configuration change or an ingestion run appears to have gone quiet.

Pass exactly one of workspace_id or project_id. Passing both, or neither, returns an error. The two scopes hit different endpoints and surface different jobs. Project scope also reveals the downstream sync jobs, such as engagement-search-update and engagement-lookup-update, that push item collection data onward and never appear at the workspace level. Which job types show up in which scope isn't fully verified against live data yet, so if an unfiltered query comes back empty, try the other scope. The meta.note field often explains an empty result, and it doesn't mean the call failed.

Narrow results with resource_type and resource_id. For item collection jobs, resource_id is the collection name rather than its ID, both in your filter and in the response. Pass job_id to fetch one job and poll it to completion after you trigger a pipeline. Neither the filters nor job_id can be combined with page_token, because the token already encodes the filters and the backend would otherwise ignore your ID. To page forward, take the page_token query parameter out of the meta.next_page URL and pass it on the next call in the same scope. Tokens are opaque and scope-bound, so don't carry one from a workspace call into a project call. A job ID from one scope isn't visible from the other. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str \| null`	No	The workspace ID returned by `list_workspaces`. Mutually exclusive with `project_id`. Prefer this scope unless you're looking for project-scoped downstream sync jobs.
`project_id`	`str \| null`	No	The project ID returned by `list_projects`. Mutually exclusive with `workspace_id`.
`limit`	`int`	No	The number of jobs to return. Defaults to `10`, with a maximum of `100`.
`page_token`	`str \| null`	No	The pagination cursor for the next page, taken from the `page_token` query parameter in the `meta.next_page` URL. Omit for the first page. Can't be combined with the filter parameters or `job_id`.
`resource_type`	`str \| null`	No	Filter by resource type, such as `item-collection`. Can't be used with `page_token`.
`resource_id`	`str \| null`	No	Filter by resource ID. For item collection jobs, this is the collection name, not the ID. Can't be used with `page_token`.
`target_resource_type`	`str \| null`	No	Filter by target resource type. Can't be used with `page_token`.
`target_resource_id`	`str \| null`	No	Filter by target resource ID. For item collection jobs, this is the collection name, not the ID. Can't be used with `page_token`.
`job_id`	`str \| null`	No	Fetch a single job by its ID, taken from a previous call in the same scope. Use it to poll one job to completion. Can't be combined with `page_token`.

Exactly one of workspace_id or project_id is required.

Response parameters

The tool returns a DataHubJobsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[dict[str, Any]]`	The job records, returned as freeform JSON.
`meta`	`DataHubJobsMeta \| null`	Pagination metadata.
`error`	`str \| null`	Error message if the request failed.

The DataHubJobsMeta object has the following fields:

Field	Type	Description
`limit`	`int \| null`	The maximum number of jobs returned per page.
`next_page`	`str \| null`	The full URL for the next page. Extract its `page_token` query parameter for the next call in the same scope. A `null` value means this is the last page.
`prev_page`	`str \| null`	The full URL for the previous page. A `null` value means this is the first page.
`note`	`str \| null`	Guidance when the result set is empty, such as trying the other scope or loosening the filters. The call still succeeded.

get_datahub_system_configuration

Gets the global Data hub system attribute model: the built-in fields such as price, brand, and title that exist across every workspace and collection. Read it when you're interpreting a collection schema and need to tell system-managed fields apart from the custom attributes your team defined. Pair it with get_item_collection_configuration and compare the system family against the main family.

The response is the same static catalog no matter which workspace you name, so workspace_id is there for authentication and base URL resolution rather than to scope the result. Unlike a collection configuration, this response carries attributes only. There are no identifiers, no destinations, no etag, and no timestamps. Some attributes appear at both the parent and variant levels, such as active, brand, and price, while others are level-specific: default_variant is variant-only and category_paths is parent-only. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str`	Yes	The workspace ID returned by `list_workspaces`. Required for authentication and base URL resolution, even though the response isn't workspace-specific.

Response parameters

The tool returns a SystemConfigurationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`SystemConfiguration \| null`	The global system attribute model.
`details`	`list[Any]`	Additional detail messages from the API.
`error`	`str \| null`	Error message if the request failed.

The SystemConfiguration object has the following fields:

Field	Type	Description
`system_schema`	`SystemConfigurationSchema \| null`	The system attribute schema definitions. The API field name is `schema`.

The SystemConfigurationSchema object has the following fields:

Field	Type	Description
`attributes`	`list[SystemAttribute]`	The built-in system attribute definitions, shared by all workspaces.

The SystemAttribute object has the following fields:

Field	Type	Description
`item_type`	`str`	The item type this attribute applies to, always `product`.
`family`	`str`	The attribute family, always `system` for built-in fields.
`level`	`str`	The schema level: `parent` for product-level, or `variant`.
`data_type`	`str`	The attribute data type, such as `String`, `Boolean`, `Float`, or `List.String`.
`description`	`str`	A human-readable description of the attribute.
`display_name`	`str`	The label shown in the UI.
`name`	`str`	The machine-readable attribute name, such as `price` or `brand`.