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
)

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 starting them on real performers. 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.

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 Marks one assignment as accepted
add_message_thread_to_folders Adds a message chain to one or more folders ("unread", "important" etc.)
aggregate_solutions_by_pool Starts aggregation of solutions in the pool
aggregate_solutions_by_task Starts aggregation of solutions to a single task
archive_app_project Archiving the 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 message to performer
create_app_batch Creating a new batch.
create_app_item Adding a new work item.
create_app_items Creating a batch of new items.
create_app_project Creating a new App project.
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 the performer
create_user_bonuses Creates many user bonuses
create_user_bonuses_async Issues payments directly to the performers, asynchronously creates many user bonuses
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 Gets aggregated responses after the AggregatedSolutionOperation completes.
find_app_batches Finds all batches in the App project that match certain rules.
find_app_items Finds all work items in the App project that match certain rules.
find_app_projects Finds all App projects that match certain rules.
find_apps Finds all Apps that match certain rules.
find_assignments Finds all assignments that match certain rules
find_attachments Finds all attachments that match certain rules
find_message_threads Finds all message threads that match certain rules
find_pools Finds all pools that match certain rules
find_projects Finds all projects that match certain rules
find_skills Finds all skills that match certain rules
find_task_suites Finds all task suites that match certain rules
find_tasks Finds tasks that match certain criteria.
find_trainings Finds all trainings that match certain rules
find_user_bonuses Finds all user bonuses that match certain rules
find_user_restrictions Finds all user restrictions that match certain rules
find_user_skills Finds all user skills that match certain rules
find_webhook_subscriptions Finds all webhook-subscriptions that match certain rules
get_aggregated_solutions Finds all aggregated responses after the AggregatedSolutionOperation completes
get_analytics Sends analytics queries, for example, to estimate the percentage of completed tasks in the pool
get_app Information about the App.
get_app_batch Batch information.
get_app_batches Finds all batches in the App project that match certain rules and returns them in an iterable object.
get_app_item Information about one work item.
get_app_items Finds all work items in the App project that match certain rules and returns them in an iterable object.
get_app_project Project information.
get_app_projects Finds all App projects that match certain rules and returns them in an iterable object.
get_apps Finds all Apps that match certain rules and returns them in an iterable object.
get_assignment Reads one specific assignment
get_assignments Finds all assignments that match certain rules and returns them in an iterable object
get_assignments_df Downloads assignments as pandas.DataFrame
get_attachment Gets attachment metadata without downloading it
get_attachments Finds all attachments that match certain rules and returns their metadata in an iterable object
get_message_threads Finds all message threads that match certain rules and returns them in an iterable object
get_operation Reads information about operation
get_operation_log Reads information about validation errors and which task (or task suites) were created
get_pool Reads one specific pool
get_pools Finds all pools that match certain rules and returns them in an iterable object
get_project Reads one specific project
get_projects Finds all projects that match certain rules and returns them in an iterable object
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 rules and returns them in an iterable object
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 rules and returns them in an iterable object
get_tasks Finds all tasks that match certain criteria.
get_training Reads one specific training
get_trainings Finds all trainings that match certain rules and returns them in an iterable object
get_user_bonus Reads one specific user bonus
get_user_bonuses Finds all user bonuses that match certain rules and returns them in an iterable object
get_user_restriction Reads one specific user restriction
get_user_restrictions Finds all user restrictions that match certain rules and returns them in an iterable object
get_user_skill Gets the value of the user's skill
get_user_skills Finds all user skills that match certain rules and returns them in an iterable object
get_webhook_subscription Get one specific webhook-subscription
get_webhook_subscriptions Finds all webhook-subscriptions that match certain rules and returns them in an iterable object
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_assignment Changes status and comment on assignment
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 users.
patch_task_suite Changes the task suite overlap or priority
patch_task_suite_overlap_or_min Stops issuing the task suites
reject_assignment Marks one assignment as rejected
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
set_user_restriction Closes the performer's access to one or more projects
set_user_skill Sets the skill value to the performer
start_app_batch Start processing the batch.
unarchive_app_project Unarchiving the 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