Registry / gcp / google-cloud-scheduler

google-cloud-scheduler

JSON →
library2.20.0pypypi✓ verified 23d ago

The `google-cloud-scheduler` Python client library allows developers to programmatically create, manage, and delete Cloud Scheduler jobs. Cloud Scheduler is a fully managed cron job service that enables you to schedule virtually any asynchronous task, such as invoking HTTP endpoints, publishing messages to Pub/Sub topics, or triggering App Engine applications. The library is actively maintained by Google, with frequent releases, and is currently at version 2.19.0.

pip install google-cloud-scheduler
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-SCHED
G
google-cloud-scheduler
gcppythonv2.20.0
Install
5.5s avg
Import
1394ms
Disk
68MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.634s · 69.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.5s · import 1.154s · 68MB
68MB installed
● package 68MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CloudSchedulerClient
from google.cloud import scheduler_v1
from google.cloud.scheduler import CloudSchedulerClient
The client class is nested under the `scheduler_v1` module, representing the v1 API.
CloudSchedulerClient (v1beta1)
from google.cloud import scheduler_v1beta1
Use this import for the beta version of the API. Generally, `v1` is preferred for production unless specific beta features are required.

This quickstart demonstrates how to create a simple Cloud Scheduler job that triggers an HTTP endpoint every hour using the `scheduler_v1` API. Ensure your `GCP_PROJECT_ID`, `GCP_LOCATION_ID`, `SCHEDULER_JOB_NAME`, and `SCHEDULER_TARGET_URL` environment variables are set or replaced in the code. Authentication is handled automatically via Application Default Credentials if running in a Google Cloud environment or with `gcloud auth application-default login` locally.

import os from google.cloud import scheduler_v1 project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id') location_id = os.environ.get('GCP_LOCATION_ID', 'us-central1') # e.g., 'us-central1' job_name = os.environ.get('SCHEDULER_JOB_NAME', 'my-scheduled-job') target_url = os.environ.get('SCHEDULER_TARGET_URL', 'https://your-http-endpoint.cloudfunctions.net/myFunction') # Initialize a client client = scheduler_v1.CloudSchedulerClient() # Construct the full resource name of the parent of the job parent = client.location_path(project_id, location_id) # Construct the job body job = scheduler_v1.Job() job.name = client.job_path(project_id, location_id, job_name) job.description = 'My first Cloud Scheduler job (Python client)' job.schedule = '0 * * * *' # Run every hour job.time_zone = 'America/Los_Angeles' # Configure an HTTP target http_target = scheduler_v1.HttpTarget() http_target.uri = target_url http_target.http_method = scheduler_v1.HttpMethod.POST job.http_target = http_target # Create the job try: response = client.create_job(parent=parent, job=job) print(f'Created job: {response.name}') except Exception as e: print(f'Error creating job: {e}') # To delete the job (uncomment to run) # try: # client.delete_job(name=response.name) # print(f'Deleted job: {response.name}') # except Exception as e: # print(f'Error deleting job: {e}')
Debug
Known issues
breakingThe library explicitly requires Python 3.9 or newer. Running on older Python versions (3.8 or below) will result in installation failures or runtime errors.
fix
Upgrade your Python environment to 3.9 or higher. For example, using `pyenv` or updating your system's Python installation.
affects: <2.19.0 (earlier versions might support older Python, but 2.19.0+ requires >=3.9)
gotchaAuthentication is a common source of errors. The client library uses Application Default Credentials (ADC) by default, but it must be correctly configured in your environment (e.g., via `gcloud auth application-default login` locally, or by attaching a service account to your compute resource in GCP). Incorrect permissions for the executing service account (e.g., lacking `roles/cloudscheduler.admin` or permissions to invoke the target) will lead to 401/403 errors.
gotchaGoogle Cloud client libraries often offer multiple API versions (e.g., `v1`, `v1beta1`). While `v1beta1` might contain newer features, it is a beta API and not guaranteed to be stable or backward compatible. Always prefer `v1` for production workloads to ensure stability and avoid unexpected breaking changes.
fix
Use `from google.cloud import scheduler_v1` for stable production code. Only use `scheduler_v1beta1` if you explicitly require a beta feature and understand the implications.
affects: All versions where `v1beta1` exists alongside `v1`
gotchaIncorrectly configuring job targets (HTTP, Pub/Sub, App Engine) can lead to silent failures or unexpected behavior. Pay close attention to `uri`, `http_method`, `headers`, `schedule` (cron format), and `time_zone`. For HTTP targets, ensure the `Content-Type` header is explicitly set if your endpoint expects a specific type, as `application/octet-stream` is a common default.
gotchaCloud Scheduler jobs have a default timeout (e.g., 30 minutes for HTTP targets). If your scheduled task is long-running and exceeds this, Cloud Scheduler will report a failure even if the downstream service eventually succeeds. Also, retry configurations must be carefully tuned to avoid overwhelming the target or incurring excessive costs.
Errors
Common errors & fixes
INVALID_ARGUMENT (often seen with HTTP 400 in logs)
The job configuration, particularly for HTTP targets, contains invalid or improperly formatted data that the target service cannot process (e.g., incorrect URI, missing 'Content-Type' header, or a malformed body payload).
fix
Ensure the 'uri', 'http_method', 'headers', and 'body' in your job's 'http_target' configuration precisely match the expectations of the target service. For Cloud Functions/Run, explicitly include `"Content-Type": "application/json"` in headers and an empty JSON body `{}` if no actual payload is needed:
```python
job = {
    'http_target': {
        'uri': 'https://your-target-url.cloudfunctions.net/your_function',
        'http_method': 'POST',
        'headers': {
            'Content-Type': 'application/json'
        },
        'body': b'{}' # or json.dumps({'key': 'value'}).encode('utf-8')
    },
    'schedule': '0 9 * * *',
    'time_zone': 'America/Los_Angeles'
}
```
PERMISSION_DENIED (HTTP 403 Forbidden) or URL_ERROR-ERROR_AUTHENTICATION (HTTP 401 Unauthorized)
The service account associated with the Cloud Scheduler job lacks the necessary IAM permissions to invoke its designated target service (e.g., Cloud Run, Cloud Functions, Workflows) or to perform core Cloud Scheduler operations.
fix
Grant the appropriate IAM roles to the service account used by the Cloud Scheduler job. Common roles include `roles/cloudscheduler.serviceAgent` for Cloud Scheduler itself and `roles/run.invoker` for Cloud Run targets, or `roles/workflow.invoker` for Cloud Workflows targets. You can do this via the GCP Console or `gcloud` command line:
```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member='serviceAccount:SERVICE_ACCOUNT_EMAIL' \
    --role='roles/run.invoker'
```
AttributeError: 'CloudSchedulerClient' object has no attribute 'location_path'
The method `location_path` for constructing resource names has been deprecated or renamed in newer versions of the `google-cloud-scheduler` Python client library.
fix
Use `client.common_location_path` instead of `client.location_path`, or construct the parent path string directly as `f"projects/{project_id}/locations/{location_id}"`:
```python
from google.cloud import scheduler_v1

client = scheduler_v1.CloudSchedulerClient()
project_id = 'your-project-id'
location_id = 'your-location-id'

# Option 1: Using common_location_path
parent = client.common_location_path(project_id, location_id)

# Option 2: Constructing the string directly
# parent = f"projects/{project_id}/locations/{location_id}"

# Now use 'parent' in methods like list_jobs or create_job
# for element in client.list_jobs(parent=parent):
#     print(element)
```
ModuleNotFoundError: No module named 'google.cloud.scheduler_v1' (or similar for 'google.cloud.scheduler')
The `google-cloud-scheduler` library is not installed in the Python environment, or the Python environment where the code is being run (e.g., local virtual environment, Cloud Run, Cloud Functions) does not have access to the installed package.
fix
Ensure the `google-cloud-scheduler` library is installed in your environment. If running locally, activate your virtual environment and run:
```bash
pip install google-cloud-scheduler
```
If deploying to Cloud Run or Cloud Functions, make sure `google-cloud-scheduler` is listed in your `requirements.txt` file.
Upgrade
Version history
2.20.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
PythonrequiredRequired Python version as specified by the package metadata.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
google-cloud-scheduler — pip install google-cloud-scheduler · libregistry