Tasks#

class TasksClient(*, sdk_config: SDKConfiguration, generated_client: ApiClient)[source]#

Bases: object

Client for managing Arize tasks and task runs.

This class is primarily intended for internal use within the SDK. Users are highly encouraged to access resource-specific functionality via arize.ArizeClient.

The tasks client is a thin wrapper around the generated REST API client, using the shared generated API client owned by arize.config.SDKConfiguration.

Parameters:

  • sdk_config (SDKConfiguration) – Resolved SDK configuration.

  • generated_client (ApiClient) – Shared generated API client instance.

list(*, name: str | None = None, project: str | None = None, dataset: str | None = None, space: str | None = None, task_type: TaskType | None = None, limit: int = 100, cursor: str | None = None) → TasksList200Response[source]#

List tasks the user has access to.

Results support cursor-based pagination. Optionally filter by space, project, dataset, or task type.

Parameters:

  • name (str | None) – Optional case-insensitive substring filter on the task name.

  • project (str | None) – Optional project name or global ID (base64) to filter results. If the value is a name, space must also be provided.

  • dataset (str | None) – Optional dataset name or global ID (base64) to filter results. If the value is a name, space must also be provided.

  • space (str | None) – Optional space name or ID used to disambiguate name-based resolution for project and dataset. If the value is a base64-encoded resource ID it is treated as a space ID; otherwise it is used as a case-insensitive substring filter on the space name.

  • task_type (TaskType | None) – Optional task type filter. One of "template_evaluation" or "code_evaluation".

  • limit (int) – Maximum number of tasks to return (1-100).

  • cursor (str | None) – Opaque pagination cursor from a previous response.

Returns:

A paginated task list response from the Arize REST API.

Raises:

ApiException – If the API request fails.

Return type:

TasksList200Response

get(*, task: str, space: str | None = None) → Task[source]#

Get a task by name or ID.

Parameters:

  • task (str) – Task name or global ID (base64). If the value looks like an ID it is used directly; otherwise it is resolved by name.

  • space (str | None) – Optional space name or ID used to disambiguate the task lookup. Recommended when resolving by name.

Returns:

The task with its full configuration.

Raises:

ApiException – If the API request fails (for example, task not found).

Return type:

Task

create(*, name: str, task_type: TaskType, evaluators: builtins.list[TasksCreateRequestEvaluatorsInner], project: str | None = None, dataset: str | None = None, space: str | None = None, experiment_ids: builtins.list[str] | None = None, sampling_rate: float | None = None, is_continuous: bool | None = None, query_filter: str | None = None) → Task[source]#

Create a new evaluation task.

Either project or dataset must be provided, but not both. When dataset is provided, at least one experiment_ids entry is required.

Parameters:

  • name (str) – Task name (must be unique within the space).

  • task_type (TaskType) – Task type. One of "template_evaluation" or "code_evaluation".

  • evaluators (builtins.list[TasksCreateRequestEvaluatorsInner]) –

    List of evaluators to attach. At least one is required. Each evaluator is a arize.tasks.types.TasksCreateRequestEvaluatorsInner with the following fields:

    • evaluator_id — Evaluator global ID (base64). Required.

    • query_filter — Per-evaluator filter (AND-ed with task-level filter). Optional.

    • column_mappings — Maps template variable names to column names. Optional.

  • project (str | None) – Project name or global ID (base64). Required when dataset is not provided.

  • dataset (str | None) – Dataset name or global ID (base64). Required when project is not provided.

  • space (str | None) – Optional space name or ID used to disambiguate name-based resolution for project and dataset.

  • experiment_ids (builtins.list[str] | None) – Experiment global IDs (base64). Required (at least one) when dataset is provided. Must be omitted or empty for project-based tasks.

  • sampling_rate (float | None) – Fraction of data to evaluate (0-1). Only valid for project-based tasks.

  • is_continuous (bool | None) – Whether to run the task continuously. Must be True or False for project-based tasks; must be False or omitted for dataset-based tasks.

  • query_filter (str | None) – Task-level query filter applied to all evaluators.

Returns:

The newly created task.

Raises:

ApiException – If the API request fails (for example, invalid payload or name conflict).

Return type:

Task

update(*, task: str, space: str | None = None, name: str | _Missing = _MISSING, sampling_rate: float | _Missing = _MISSING, is_continuous: bool | _Missing = _MISSING, query_filter: str | None | _Missing = _MISSING, evaluators: builtins.list[TasksCreateRequestEvaluatorsInner] | _Missing = _MISSING) → Task[source]#

Update mutable fields on an existing task.

At least one mutable field must be provided. Pass None to query_filter to clear the existing filter; omit the argument to leave it unchanged.

Parameters:

  • task (str) – Task name or global ID (base64). Names are resolved within the space when space is provided.

  • space (str | None) – Optional space name or ID used to disambiguate task name resolution.

  • name (str | _Missing) – New display name for the task.

  • sampling_rate (float | _Missing) – Fraction of data to evaluate (0-1). Project-based tasks only.

  • is_continuous (bool | _Missing) – Whether the task runs continuously.

  • query_filter (str | None | _Missing) – Task-level query filter, or None to clear the filter.

  • evaluators (builtins.list[TasksCreateRequestEvaluatorsInner] | _Missing) – Full replacement list of evaluators (at least one when provided).

Returns:

The updated task.

Raises:

  • ValueError – If no update fields were provided.

  • ApiException – If the API request fails.

Return type:

Task

delete(*, task: str, space: str | None = None) → None[source]#

Delete a task and its associated configuration.

Parameters:

  • task (str) – Task name or global ID (base64).

  • space (str | None) – Optional space name or ID used when resolving by task name.

Raises:

ApiException – If the API request fails.

Return type:

None

trigger_run(*, task: str, space: str | None = None, data_start_time: datetime | None = None, data_end_time: datetime | None = None, max_spans: int | None = None, override_evaluations: bool | None = None, experiment_ids: builtins.list[str] | None = None) → TaskRun[source]#

Trigger an on-demand run for a task.

Parameters:

  • task (str) – Task name or global ID (base64) to trigger a run for.

  • space (str | None) – Optional space name or ID used to disambiguate the task lookup. Recommended when resolving by name.

  • data_start_time (datetime | None) – Optional ISO 8601 start of the data window to evaluate.

  • data_end_time (datetime | None) – Optional ISO 8601 end of the data window to evaluate. Defaults to now when omitted.

  • max_spans (int | None) – Maximum number of spans to process (default 10 000).

  • override_evaluations (bool | None) – Whether to re-evaluate data that already has evaluation labels. Defaults to False.

  • experiment_ids (builtins.list[str] | None) – Experiment global IDs (base64) to run against. Only applicable for dataset-based tasks.

Returns:

The newly created task run (initially in "pending" status).

Raises:

ApiException – If the API request fails.

Return type:

TaskRun

list_runs(*, task: str, space: str | None = None, status: RunStatus | None = None, limit: int = 100, cursor: str | None = None) → TasksListRuns200Response[source]#

List runs for a task.

Results support cursor-based pagination. Optionally filter by run status.

Parameters:

  • task (str) – Task name or global ID (base64) to list runs for.

  • space (str | None) – Optional space name or ID used to disambiguate the task lookup. Recommended when resolving by name.

  • status (RunStatus | None) – Optional run status filter. One of "pending", "running", "completed", "failed", or "cancelled".

  • limit (int) – Maximum number of runs to return (1-100).

  • cursor (str | None) – Opaque pagination cursor from a previous response.

Returns:

A paginated task run list response from the Arize REST API.

Raises:

ApiException – If the API request fails.

Return type:

TasksListRuns200Response

get_run(*, run_id: str) → TaskRun[source]#

Get a task run by its global ID.

Parameters:

run_id (str) – Task run global ID (base64) to retrieve.

Returns:

The task run with its current status and statistics.

Raises:

ApiException – If the API request fails (for example, run not found).

Return type:

TaskRun

cancel_run(*, run_id: str) → TaskRun[source]#

Cancel a task run.

Only valid when the run’s current status is "pending" or "running".

Parameters:

run_id (str) – Task run global ID (base64) to cancel.

Returns:

The updated task run with status "cancelled".

Raises:

ApiException – If the API request fails (for example, run not found or already in terminal state).

Return type:

TaskRun

wait_for_run(*, run_id: str, poll_interval: float = _DEFAULT_POLL_INTERVAL, timeout: float = _DEFAULT_TIMEOUT) → TaskRun[source]#

Poll a task run until it reaches a terminal state.

Repeatedly calls get_run at poll_interval-second intervals until the run’s status is one of "completed", "failed", or "cancelled", or until timeout seconds have elapsed.

Parameters:

  • run_id (str) – Task run global ID (base64) to wait for.

  • poll_interval (float) – Seconds between polling attempts. Defaults to 5.

  • timeout (float) – Maximum seconds to wait before raising TimeoutError. Defaults to 600.

Returns:

The task run in its terminal state.

Raises:

  • ValueError – If timeout or poll_interval is not positive.

  • TimeoutError – If the run does not reach a terminal state within timeout seconds.

  • ApiException – If any polling request fails.

Return type:

TaskRun

Response Types#

class Task(*, id: Annotated[str, Strict(strict=True)], name: Annotated[str, Strict(strict=True)], type: Annotated[str, Strict(strict=True)], project_id: Annotated[str, Strict(strict=True)] | None = None, dataset_id: Annotated[str, Strict(strict=True)] | None = None, sampling_rate: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])] | Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])] | None = None, is_continuous: Annotated[bool, Strict(strict=True)], query_filter: Annotated[str, Strict(strict=True)] | None, evaluators: List[TaskEvaluator], experiment_ids: List[Annotated[str, Strict(strict=True)]], last_run_at: datetime | None, created_at: datetime, updated_at: datetime, created_by_user_id: Annotated[str, Strict(strict=True)] | None)[source]#

Bases: BaseModel

A task is a typed, configurable unit of work that ties one or more evaluators to a data source (project or dataset).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • id (Annotated[str, Strict(strict=True)])

  • name (Annotated[str, Strict(strict=True)])

  • type (Annotated[str, Strict(strict=True)])

  • project_id (Annotated[str, Strict(strict=True)] | None)

  • dataset_id (Annotated[str, Strict(strict=True)] | None)

  • sampling_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])] | Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])] | None)

  • is_continuous (Annotated[bool, Strict(strict=True)])

  • query_filter (Annotated[str, Strict(strict=True)] | None)

  • evaluators (List[TaskEvaluator])

  • experiment_ids (List[Annotated[str, Strict(strict=True)]])

  • last_run_at (datetime | None)

  • created_at (datetime)

  • updated_at (datetime)

  • created_by_user_id (Annotated[str, Strict(strict=True)] | None)

id: StrictStr#
name: StrictStr#
type: StrictStr#
project_id: StrictStr | None#
dataset_id: StrictStr | None#
sampling_rate: Annotated[float, Field(le=1, strict=True, ge=0)] | Annotated[int, Field(le=1, strict=True, ge=0)] | None#
is_continuous: StrictBool#
query_filter: StrictStr | None#
evaluators: List[TaskEvaluator]#
experiment_ids: List[StrictStr]#
last_run_at: datetime | None#
created_at: datetime#
updated_at: datetime#
created_by_user_id: StrictStr | None#
classmethod type_validate_enum(value)[source]#

Validates the enum

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of Task from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of Task from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

class TaskRun(*, id: Annotated[str, Strict(strict=True)], task_id: Annotated[str, Strict(strict=True)], status: Annotated[str, Strict(strict=True)], run_started_at: datetime | None, run_finished_at: datetime | None, data_start_time: datetime | None, data_end_time: datetime | None, num_successes: Annotated[int, Strict(strict=True)], num_errors: Annotated[int, Strict(strict=True)], num_skipped: Annotated[int, Strict(strict=True)], created_at: datetime, created_by_user_id: Annotated[str, Strict(strict=True)] | None)[source]#

Bases: BaseModel

A task run is an async job that executes the work defined on a task.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
id: StrictStr#
task_id: StrictStr#
status: StrictStr#
run_started_at: datetime | None#
run_finished_at: datetime | None#
data_start_time: datetime | None#
data_end_time: datetime | None#
num_successes: StrictInt#
num_errors: StrictInt#
num_skipped: StrictInt#
created_at: datetime#
created_by_user_id: StrictStr | None#
classmethod status_validate_enum(value)[source]#

Validates the enum

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of TaskRun from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of TaskRun from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

class TasksList200Response(*, tasks: List[Task], pagination: PaginationMetadata)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • tasks (List[Task])

  • pagination (PaginationMetadata)

tasks: List[Task]#
pagination: PaginationMetadata#
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of TasksList200Response from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of TasksList200Response from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

to_df(by_alias: bool = False, exclude_none: str | bool = True, json_normalize: bool = False, convert_dtypes: bool = True, expand_field: str = 'additional_properties', expand_prefix: str = '') → pd.DataFrame#

Convert a list of objects to a pandas.DataFrame.

Behavior:

  • If an item is a Pydantic v2 model, use .model_dump(by_alias=…).

  • If an item is a mapping (dict-like), use it as-is.

  • Otherwise, raise a ValueError (unsupported row type).

Parameters:

  • self (object) – The object instance containing the field to convert.

  • by_alias (bool) – Use field aliases when dumping Pydantic models.

  • exclude_none (str | bool) – Control None/NaN column dropping. - False: keep Nones as-is - “all”: drop columns where all values are None/NaN - “any”: drop columns where any value is None/NaN - True: alias for “all”

  • json_normalize (bool) – If True, flatten nested dicts via pandas.json_normalize.

  • convert_dtypes (bool) – If True, call DataFrame.convert_dtypes() at the end.

  • expand_field (str) – If set, look for this field in each row and

  • columns. (expand its keys into top-level)

  • expand_prefix (str) – If set, prefix expanded column names with this string.

Returns:

The converted DataFrame.

Return type:

pandas.DataFrame

class TasksListRuns200Response(*, task_runs: List[TaskRun], pagination: PaginationMetadata)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • task_runs (List[TaskRun])

  • pagination (PaginationMetadata)

task_runs: List[TaskRun]#
pagination: PaginationMetadata#
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of TasksListRuns200Response from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of TasksListRuns200Response from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

to_df(by_alias: bool = False, exclude_none: str | bool = True, json_normalize: bool = False, convert_dtypes: bool = True, expand_field: str = 'additional_properties', expand_prefix: str = '') → pd.DataFrame#

Convert a list of objects to a pandas.DataFrame.

Behavior:

  • If an item is a Pydantic v2 model, use .model_dump(by_alias=…).

  • If an item is a mapping (dict-like), use it as-is.

  • Otherwise, raise a ValueError (unsupported row type).

Parameters:

  • self (object) – The object instance containing the field to convert.

  • by_alias (bool) – Use field aliases when dumping Pydantic models.

  • exclude_none (str | bool) – Control None/NaN column dropping. - False: keep Nones as-is - “all”: drop columns where all values are None/NaN - “any”: drop columns where any value is None/NaN - True: alias for “all”

  • json_normalize (bool) – If True, flatten nested dicts via pandas.json_normalize.

  • convert_dtypes (bool) – If True, call DataFrame.convert_dtypes() at the end.

  • expand_field (str) – If set, look for this field in each row and

  • columns. (expand its keys into top-level)

  • expand_prefix (str) – If set, prefix expanded column names with this string.

Returns:

The converted DataFrame.

Return type:

pandas.DataFrame

class TasksCreateRequestEvaluatorsInner(*, evaluator_id: Annotated[str, Strict(strict=True)], query_filter: Annotated[str, Strict(strict=True)] | None = None, column_mappings: Dict[str, Annotated[str, Strict(strict=True)]] | None = None)[source]#

Bases: BaseModel

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
evaluator_id: StrictStr#
query_filter: StrictStr | None#
column_mappings: Dict[str, StrictStr] | None#
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'protected_namespaces': (), 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_str() → str[source]#

Returns the string representation of the model using alias

Return type:

str

to_json() → str[source]#

Returns the JSON representation of the model using alias

Return type:

str

classmethod from_json(json_str: str) → Self | None[source]#

Create an instance of TasksCreateRequestEvaluatorsInner from a JSON string

Parameters:

json_str (str)

Return type:

Self | None

to_dict() → Dict[str, Any][source]#

Return the dictionary representation of the model using alias.

This has the following differences from calling pydantic’s self.model_dump(by_alias=True):

  • None is only added to the output dict for nullable fields that were set at model initialization. Other fields with value None are ignored.

Return type:

Dict[str, Any]

classmethod from_dict(obj: Dict[str, Any] | None) → Self | None[source]#

Create an instance of TasksCreateRequestEvaluatorsInner from a dict

Parameters:

obj (Dict[str, Any] | None)

Return type:

Self | None

On this page