Toloka documentation

TolokaClient

toloka.client.TolokaClient | Source code

TolokaClient(
    self,
    token: str,
    environment: Union[Environment, str, None] = None,
    retries: Union[int, Retry] = 3,
    timeout: Union[float, Tuple[float, float]] = 10.0,
    url: Optional[str] = None,
    retry_quotas: Union[List[str], str, None] = 'MIN',
    retryer_factory: Optional[Callable[[], Retry]] = None,
    act_under_account_id: Optional[str] = None
)

Class that implements interaction with Toloka API.

Objects of other classes are created and modified only in memory of your computer. You can transfer information about these objects to Toloka only by calling one of the TolokaClient methods.

For example, creating an instance of Project class will not add a project to Toloka right away. It will create a Project instance in your local memory. You need to call the TolokaClient.create_project method and pass the created project instance to it. Likewise, if you read a project using the TolokaClient.get_project method, you will get an instance of Project class. But if you change some parameters in this object manually in your code, it will not affect the existing project in Toloka. Call TolokaClient.update_project and pass the Project to apply your changes.

Parameters Description

Parameters Type Description
token str

Your OAuth token for Toloka. You can learn more about how to get it here

environment Union[Environment, str, None]

There are two environments in Toloka:

  • SANDBOXTesting environment for Toloka requesters. You can test complex projects before assigning tasks to Tolokers. Nobody will see your tasks, and it's free.
  • PRODUCTIONProduction environment for Toloka requesters. You spend money there and get the results.

You need to register in each environment separately. OAuth tokens are generated in each environment separately too.

Default value: None.

retries Union[int, Retry]

Retry policy for failed API requests. Possible values:

  • int — The number of retries for all requests. In this case, the retry policy is created automatically.
  • Retry object — Deprecated type. Use retryer_factory parameter instead.

Default value: 3.

timeout Union[float, Tuple[float, float]]

Number of seconds that Requests library will wait for your client to establish connection to a remote machine. Possible values:

  • float — Single value for both connect and read timeouts.
  • Tuple[float, float] — Tuple sets the values for connect and read timeouts separately.
  • None — Set the timeout to None only if you are willing to wait the Response for unlimited number of seconds.

Default value: 10.0.

url Optional[str]

Set a specific URL instead of Toloka environment. May be useful for testing purposes. You can only set one parameter — either url or environment, not both of them.

Default value: None.

retry_quotas Union[List[str], str, None]

List of quotas that must be retried. Set None or pass an empty list for not retrying any quotas. If you specified the retries as Retry instance, you must set this parameter to None. Possible values:

  • MIN - Retry minutes quotas.
  • HOUR - Retry hourly quotas. This means that the program just sleeps for an hour.
  • DAY - Retry daily quotas. We do not recommend retrying these quotas.

Default value: MIN.

retryer_factory Optional[Callable[[], Retry]]

Factory that creates Retry object. Fully specified retry policy that will apply to all requests.

Default value: None.

act_under_account_id Optional[str]

ID of the requester that has been shared access with the current token owner account. All requests will be made using a specified account. See Shared access to the requester's account documentation page. ID of the requester can be retrieved using the get_requester method (this method should be called by the account owner using account's token).

Examples:

How to create TolokaClient instance and make your first request to Toloka.

your_oauth_token = input('Enter your token:')
toloka_client = toloka.TolokaClient(your_oauth_token, 'PRODUCTION')  # Or switch to 'SANDBOX' environment

Note

toloka_client instance will be used to pass all API calls later on.

Methods Summary

Method Description
accept_assignment Accepts an assignment.
add_message_thread_to_folders Adds a message chain to one or more folders ("unread", "important" etc.)
aggregate_solutions_by_pool Starts aggregation of responses in all completed tasks in a pool.
aggregate_solutions_by_task Aggregates responses to a single task on the Toloka server.
archive_app_project Archives an App project.
archive_pool Sends pool to archive
archive_pool_async Sends pool to archive, asynchronous version
archive_project Sends project to archive
archive_project_async Sends project to archive, asynchronous version
archive_training Sends training to archive
archive_training_async Sends training to archive, asynchronous version
clone_pool Duplicates existing pool
clone_pool_async Duplicates existing pool, asynchronous version
clone_project Synchronously clones the project, all pools and trainings
clone_training Duplicates existing training
clone_training_async Duplicates existing training, asynchronous version
close_pool Stops distributing tasks from the pool
close_pool_async Stops distributing tasks from the pool, asynchronous version
close_pool_for_update Closes pool for update
close_pool_for_update_async Closes pool for update, asynchronous version
close_training Stops distributing tasks from the training
close_training_async Stops distributing tasks from the training, asynchronous version
compose_message_thread Sends a message to a Toloker.
create_app_batch Creates a batch with task items in an App project in Toloka.
create_app_item Creates an App task item in Toloka.
create_app_items Creates task items in an App project in Toloka and adds them to an existing batch.
create_app_project Creates an App project in Toloka.
create_pool Creates a new pool
create_project Creates a new project
create_skill Creates a new Skill
create_task Creates a new task in Toloka.
create_task_suite Creates a new task suite
create_task_suites Creates many task suites in pools
create_task_suites_async Creates many task suites in pools, asynchronous version
create_tasks Creates several tasks in Toloka using a single request.
create_tasks_async Creates tasks in Toloka asynchronously.
create_training Creates a new training
create_user_bonus Issues payments directly to a Toloker.
create_user_bonuses Creates rewards for Tolokers.
create_user_bonuses_async Issues payments directly to Tolokers, asynchronously creates many UserBonus instances.
delete_user_restriction Unlocks existing restriction
delete_user_skill Drop specific UserSkill
delete_webhook_subscription Drop specific webhook-subscription
download_attachment Downloads specific attachment
find_aggregated_solutions Finds aggregated responses that match certain criteria.
find_app_batches Finds batches that match certain criteria in an App project.
find_app_items Finds task items that match certain criteria in an App project.
find_app_projects Finds App projects that match certain criteria.
find_apps Finds App solutions that match certain criteria.
find_assignments Finds assignments that match certain criteria.
find_attachments Finds attachments that match certain criteria and returns their metadata.
find_message_threads Finds message threads that match certain criteria.
find_operations Finds operations that match certain criteria.
find_pools Finds pools that match certain criteria.
find_projects Finds projects that match certain criteria.
find_skills Finds skills that match certain criteria.
find_task_suites Finds task suites that match certain criteria.
find_tasks Finds tasks that match certain criteria.
find_trainings Finds training pools that match certain criteria.
find_user_bonuses Finds Tolokers' rewards that match certain criteria.
find_user_restrictions Finds Toloker restrictions that match certain criteria.
find_user_skills Finds Toloker's skills that match certain criteria.
find_webhook_subscriptions Finds webhook subscriptions that match certain criteria.
get_aggregated_solutions Finds all aggregated responses that match certain criteria.
get_analytics Sends analytics queries, for example, to estimate the percentage of completed tasks in the pool
get_app Gets information from Toloka about an App solution.
get_app_batch Gets information from Toloka about a batch in an App project.
get_app_batches Finds all batches that match certain criteria in an App project.
get_app_item Gets information from Toloka about an App task item.
get_app_items Finds all App task items that match certain criteria in an App project.
get_app_project Gets information from Toloka about an App project.
get_app_projects Finds all App projects that match certain criteria.
get_apps Finds all App solutions that match certain criteria.
get_assignment Gets an assignment from Toloka.
get_assignments Finds all assignments that match certain criteria.
get_assignments_df Downloads assignments as pandas.DataFrame.
get_attachment Gets attachment metadata without downloading it
get_attachments Finds all attachments that match certain criteria and returns their metadata.
get_message_threads Finds all message threads that match certain criteria.
get_operation Reads information about operation
get_operation_log Reads information about validation errors and which task (or task suites) were created
get_operations Finds all operations that match certain rules and returns them in an iterable object
get_pool Reads one specific pool
get_pools Finds all pools that match certain criteria.
get_project Reads one specific project
get_projects Finds all projects that match certain criteria.
get_requester Reads information about the customer and the account balance
get_skill Reads one specific skill
get_skills Finds all skills that match certain criteria.
get_task Gets a task with specified ID from Toloka.
get_task_suite Reads one specific task suite
get_task_suites Finds all task suites that match certain criteria.
get_tasks Finds all tasks that match certain criteria.
get_training Reads one specific training
get_trainings Finds all training pools that match certain criteria.
get_user Gets Toloker metadata by user_id.
get_user_bonus Gets information about a Toloker's reward.
get_user_bonuses Finds all Tolokers' rewards that match certain rules and returns them in an iterable object
get_user_restriction Gets information about a Toloker restriction.
get_user_restrictions Finds all Toloker restrictions that match certain criteria.
get_user_skill Gets the value of a Toloker's skill
get_user_skills Finds all Toloker's skills that match certain criteria.
get_webhook_subscription Get one specific webhook-subscription
get_webhook_subscriptions Finds all webhook subscriptions that match certain criteria.
open_pool Starts distributing tasks from the pool
open_pool_async Starts distributing tasks from the pool, asynchronous version
open_training Starts distributing tasks from the training
open_training_async Starts distributing tasks from the training, asynchronous version
patch_app_batch Updates an App batch name.
patch_assignment Changes an assignment status and associated public comment.
patch_pool Changes the priority of the pool issue
patch_task Changes a task overlap value.
patch_task_overlap_or_min Stops assigning a task to Tolokers.
patch_task_suite Changes the task suite overlap or priority
patch_task_suite_overlap_or_min Stops issuing the task suites
reject_assignment Rejects an assignment.
remove_message_thread_from_folders Deletes a message chain from one or more folders ("unread", "important" etc.)
reply_message_thread Replies to a message in thread
resume_app_batch Resumes annotation of a batch of task items in an App project.
set_user_restriction Restricts access to projects or pools for a Toloker.
set_user_skill Assigns a skill to a Toloker.
start_app_batch Launches annotation of a batch of task items in an App project.
stop_app_batch Stops annotation of a batch of task items in an App project.
unarchive_app_project Unarchives an App project.
update_pool Makes changes to the pool
update_project Makes changes to the project
update_skill Makes changes to the skill
update_training Makes changes to the training
upsert_webhook_subscriptions Creates (upsert) many webhook-subscriptions.
wait_operation Waits for the operation to complete, and return it