fix: align SDK models with the API behavior

vdusek · vdusek · commit c84671929e32 · 2026-02-18T18:39:07.000+01:00
Update Pydantic models in _models.py and storage client models to match
the typed models from apify-client-python. This adds missing fields to
Webhook, ActorRunMeta, ActorRunStats, ActorRunOptions, ActorRunUsage, and
ActorRun models, introduces new helper models (PricingModel enum,
WebhookCondition, WebhookStats, Metamorph, ActorRunUsageUsd), adds
extra='allow' to all models for forward compatibility, and fixes type
inconsistencies (Decimal vs float, timedelta vs raw int/float fields).
diff --git a/src/apify/_charging.py b/src/apify/_charging.py
@@ -156,15 +156,16 @@ async def __aenter__(self) -> None:
 
         # Set pricing model
         if self._configuration.test_pay_per_event:
-            self._pricing_model = 'PAY_PER_EVENT'
+            self._pricing_model = PricingModel.PAY_PER_EVENT
         else:
-            self._pricing_model = pricing_info.pricing_model if pricing_info is not None else None
+            self._pricing_model = PricingModel(pricing_info.pricing_model) if pricing_info else None
 
         # Load per-event pricing information
         if pricing_info is not None and isinstance(pricing_info, PayPerEventActorPricingInfo):
-            for event_name, event_pricing in pricing_info.pricing_per_event.actor_charge_events.items():
+            actor_charge_events = pricing_info.pricing_per_event.actor_charge_events or {}
+            for event_name, event_pricing in actor_charge_events.items():
                 self._pricing_info[event_name] = PricingInfoItem(
-                    price=event_pricing.event_price_usd,
+                    price=Decimal(str(event_pricing.event_price_usd)),
                     title=event_pricing.event_title,
                 )
 
@@ -355,10 +356,11 @@ async def _fetch_pricing_info(self) -> _FetchedPricingInfoDict:
             if run is None:
                 raise RuntimeError('Actor run not found')
 
+            max_charge = run.options.max_total_charge_usd
             return _FetchedPricingInfoDict(
                 pricing_info=run.pricing_info,
                 charged_event_counts=run.charged_event_counts or {},
-                max_total_charge_usd=run.options.max_total_charge_usd or Decimal('inf'),
+                max_total_charge_usd=Decimal(str(max_charge)) if max_charge is not None else Decimal('inf'),
             )
 
         # Local development without environment variables
diff --git a/src/apify/_models.py b/src/apify/_models.py
@@ -1,52 +1,120 @@
 from __future__ import annotations
 
-from datetime import datetime, timedelta
-from decimal import Decimal
-from typing import TYPE_CHECKING, Annotated, Literal
+from datetime import datetime
+from enum import Enum
+from typing import Annotated, Literal
 
 from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
 
 from apify_shared.consts import ActorJobStatus, MetaOrigin, WebhookEventType
-from crawlee._utils.models import timedelta_ms
 from crawlee._utils.urls import validate_http_url
 
 from apify._utils import docs_group
 
-if TYPE_CHECKING:
-    from typing import TypeAlias
+
+class PricingModel(str, Enum):
+    """Pricing model for an Actor."""
+
+    PAY_PER_EVENT = 'PAY_PER_EVENT'
+    PRICE_PER_DATASET_ITEM = 'PRICE_PER_DATASET_ITEM'
+    FLAT_PRICE_PER_MONTH = 'FLAT_PRICE_PER_MONTH'
+    FREE = 'FREE'
+
+
+class GeneralAccessEnum(str, Enum):
+    """Defines the general access level for the resource."""
+
+    ANYONE_WITH_ID_CAN_READ = 'ANYONE_WITH_ID_CAN_READ'
+    ANYONE_WITH_NAME_CAN_READ = 'ANYONE_WITH_NAME_CAN_READ'
+    FOLLOW_USER_SETTING = 'FOLLOW_USER_SETTING'
+    RESTRICTED = 'RESTRICTED'
+
+
+class WebhookCondition(BaseModel):
+    """Condition for triggering a webhook."""
+
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    actor_id: Annotated[str | None, Field(alias='actorId')] = None
+    actor_task_id: Annotated[str | None, Field(alias='actorTaskId')] = None
+    actor_run_id: Annotated[str | None, Field(alias='actorRunId')] = None
+
+
+class WebhookDispatchStatus(str, Enum):
+    """Status of a webhook dispatch."""
+
+    ACTIVE = 'ACTIVE'
+    SUCCEEDED = 'SUCCEEDED'
+    FAILED = 'FAILED'
+
+
+class ExampleWebhookDispatch(BaseModel):
+    """Information about a webhook dispatch."""
+
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    status: WebhookDispatchStatus
+    finished_at: Annotated[datetime, Field(alias='finishedAt')]
+
+
+class WebhookStats(BaseModel):
+    """Statistics about webhook dispatches."""
+
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    total_dispatches: Annotated[int, Field(alias='totalDispatches')]
 
 
 @docs_group('Actor')
 class Webhook(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     event_types: Annotated[
         list[WebhookEventType],
-        Field(description='Event types that should trigger the webhook'),
+        Field(alias='eventTypes', description='Event types that should trigger the webhook'),
     ]
     request_url: Annotated[
         str,
-        Field(description='URL that the webhook should call'),
+        Field(alias='requestUrl', description='URL that the webhook should call'),
         BeforeValidator(validate_http_url),
     ]
+    id: Annotated[str | None, Field(alias='id')] = None
+    created_at: Annotated[datetime | None, Field(alias='createdAt')] = None
+    modified_at: Annotated[datetime | None, Field(alias='modifiedAt')] = None
+    user_id: Annotated[str | None, Field(alias='userId')] = None
+    is_ad_hoc: Annotated[bool | None, Field(alias='isAdHoc')] = None
+    should_interpolate_strings: Annotated[bool | None, Field(alias='shouldInterpolateStrings')] = None
+    condition: Annotated[WebhookCondition | None, Field(alias='condition')] = None
+    ignore_ssl_errors: Annotated[bool | None, Field(alias='ignoreSslErrors')] = None
+    do_not_retry: Annotated[bool | None, Field(alias='doNotRetry')] = None
     payload_template: Annotated[
         str | None,
-        Field(description='Template for the payload sent by the webook'),
+        Field(alias='payloadTemplate', description='Template for the payload sent by the webhook'),
     ] = None
+    headers_template: Annotated[str | None, Field(alias='headersTemplate')] = None
+    description: Annotated[str | None, Field(alias='description')] = None
+    last_dispatch: Annotated[ExampleWebhookDispatch | None, Field(alias='lastDispatch')] = None
+    stats: Annotated[WebhookStats | None, Field(alias='stats')] = None
 
 
 @docs_group('Actor')
 class ActorRunMeta(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     origin: Annotated[MetaOrigin, Field()]
+    client_ip: Annotated[str | None, Field(alias='clientIp')] = None
+    user_agent: Annotated[str | None, Field(alias='userAgent')] = None
+    schedule_id: Annotated[str | None, Field(alias='scheduleId')] = None
+    scheduled_at: Annotated[datetime | None, Field(alias='scheduledAt')] = None
 
 
 @docs_group('Actor')
 class ActorRunStats(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     input_body_len: Annotated[int | None, Field(alias='inputBodyLen')] = None
+    migration_count: Annotated[int | None, Field(alias='migrationCount')] = None
+    reboot_count: Annotated[int | None, Field(alias='rebootCount')] = None
     restart_count: Annotated[int, Field(alias='restartCount')]
     resurrect_count: Annotated[int, Field(alias='resurrectCount')]
     mem_avg_bytes: Annotated[float | None, Field(alias='memAvgBytes')] = None
@@ -57,26 +125,47 @@ class ActorRunStats(BaseModel):
     cpu_current_usage: Annotated[float | None, Field(alias='cpuCurrentUsage')] = None
     net_rx_bytes: Annotated[int | None, Field(alias='netRxBytes')] = None
     net_tx_bytes: Annotated[int | None, Field(alias='netTxBytes')] = None
-    duration: Annotated[timedelta_ms | None, Field(alias='durationMillis')] = None
-    run_time: Annotated[timedelta | None, Field(alias='runTimeSecs')] = None
+    duration_millis: Annotated[int | None, Field(alias='durationMillis')] = None
+    run_time_secs: Annotated[float | None, Field(alias='runTimeSecs')] = None
     metamorph: Annotated[int | None, Field(alias='metamorph')] = None
     compute_units: Annotated[float, Field(alias='computeUnits')]
 
 
 @docs_group('Actor')
 class ActorRunOptions(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     build: str
-    timeout: Annotated[timedelta, Field(alias='timeoutSecs')]
+    timeout_secs: Annotated[int, Field(alias='timeoutSecs')]
     memory_mbytes: Annotated[int, Field(alias='memoryMbytes')]
     disk_mbytes: Annotated[int, Field(alias='diskMbytes')]
-    max_total_charge_usd: Annotated[Decimal | None, Field(alias='maxTotalChargeUsd')] = None
+    max_items: Annotated[int | None, Field(alias='maxItems')] = None
+    max_total_charge_usd: Annotated[float | None, Field(alias='maxTotalChargeUsd')] = None
 
 
 @docs_group('Actor')
 class ActorRunUsage(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    actor_compute_units: Annotated[float | None, Field(alias='ACTOR_COMPUTE_UNITS')] = None
+    dataset_reads: Annotated[int | None, Field(alias='DATASET_READS')] = None
+    dataset_writes: Annotated[int | None, Field(alias='DATASET_WRITES')] = None
+    key_value_store_reads: Annotated[int | None, Field(alias='KEY_VALUE_STORE_READS')] = None
+    key_value_store_writes: Annotated[int | None, Field(alias='KEY_VALUE_STORE_WRITES')] = None
+    key_value_store_lists: Annotated[int | None, Field(alias='KEY_VALUE_STORE_LISTS')] = None
+    request_queue_reads: Annotated[int | None, Field(alias='REQUEST_QUEUE_READS')] = None
+    request_queue_writes: Annotated[int | None, Field(alias='REQUEST_QUEUE_WRITES')] = None
+    data_transfer_internal_gbytes: Annotated[float | None, Field(alias='DATA_TRANSFER_INTERNAL_GBYTES')] = None
+    data_transfer_external_gbytes: Annotated[float | None, Field(alias='DATA_TRANSFER_EXTERNAL_GBYTES')] = None
+    proxy_residential_transfer_gbytes: Annotated[float | None, Field(alias='PROXY_RESIDENTIAL_TRANSFER_GBYTES')] = None
+    proxy_serps: Annotated[int | None, Field(alias='PROXY_SERPS')] = None
+
+
+@docs_group('Actor')
+class ActorRunUsageUsd(BaseModel):
+    """Resource usage costs in USD."""
+
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     actor_compute_units: Annotated[float | None, Field(alias='ACTOR_COMPUTE_UNITS')] = None
     dataset_reads: Annotated[float | None, Field(alias='DATASET_READS')] = None
@@ -92,9 +181,67 @@ class ActorRunUsage(BaseModel):
     proxy_serps: Annotated[float | None, Field(alias='PROXY_SERPS')] = None
 
 
+class Metamorph(BaseModel):
+    """Information about a metamorph event that occurred during the run."""
+
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    created_at: Annotated[datetime, Field(alias='createdAt')]
+    actor_id: Annotated[str, Field(alias='actorId')]
+    build_id: Annotated[str, Field(alias='buildId')]
+    input_key: Annotated[str | None, Field(alias='inputKey')] = None
+
+
+class CommonActorPricingInfo(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    apify_margin_percentage: Annotated[float | None, Field(alias='apifyMarginPercentage')] = None
+    created_at: Annotated[datetime | None, Field(alias='createdAt')] = None
+    started_at: Annotated[datetime | None, Field(alias='startedAt')] = None
+    notified_about_future_change_at: Annotated[datetime | None, Field(alias='notifiedAboutFutureChangeAt')] = None
+    notified_about_change_at: Annotated[datetime | None, Field(alias='notifiedAboutChangeAt')] = None
+    reason_for_change: Annotated[str | None, Field(alias='reasonForChange')] = None
+
+
+class FreeActorPricingInfo(CommonActorPricingInfo):
+    pricing_model: Annotated[Literal['FREE'], Field(alias='pricingModel')]
+
+
+class FlatPricePerMonthActorPricingInfo(CommonActorPricingInfo):
+    pricing_model: Annotated[Literal['FLAT_PRICE_PER_MONTH'], Field(alias='pricingModel')]
+    trial_minutes: Annotated[int, Field(alias='trialMinutes')]
+    price_per_unit_usd: Annotated[float, Field(alias='pricePerUnitUsd')]
+
+
+class PricePerDatasetItemActorPricingInfo(CommonActorPricingInfo):
+    pricing_model: Annotated[Literal['PRICE_PER_DATASET_ITEM'], Field(alias='pricingModel')]
+    unit_name: Annotated[str, Field(alias='unitName')]
+    price_per_unit_usd: Annotated[float, Field(alias='pricePerUnitUsd')]
+
+
+class ActorChargeEvent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    event_price_usd: Annotated[float, Field(alias='eventPriceUsd')]
+    event_title: Annotated[str, Field(alias='eventTitle')]
+    event_description: Annotated[str | None, Field(alias='eventDescription')] = None
+
+
+class PricingPerEvent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+    actor_charge_events: Annotated[dict[str, ActorChargeEvent] | None, Field(alias='actorChargeEvents')] = None
+
+
+class PayPerEventActorPricingInfo(CommonActorPricingInfo):
+    pricing_model: Annotated[Literal['PAY_PER_EVENT'], Field(alias='pricingModel')]
+    pricing_per_event: Annotated[PricingPerEvent, Field(alias='pricingPerEvent')]
+    minimal_max_total_charge_usd: Annotated[float | None, Field(alias='minimalMaxTotalChargeUsd')] = None
+
+
 @docs_group('Actor')
 class ActorRun(BaseModel):
-    __model_config__ = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     id: Annotated[str, Field(alias='id')]
     act_id: Annotated[str, Field(alias='actId')]
@@ -110,16 +257,17 @@ class ActorRun(BaseModel):
     options: Annotated[ActorRunOptions, Field(alias='options')]
     build_id: Annotated[str, Field(alias='buildId')]
     exit_code: Annotated[int | None, Field(alias='exitCode')] = None
+    general_access: Annotated[str | None, Field(alias='generalAccess')] = None
     default_key_value_store_id: Annotated[str, Field(alias='defaultKeyValueStoreId')]
     default_dataset_id: Annotated[str, Field(alias='defaultDatasetId')]
     default_request_queue_id: Annotated[str, Field(alias='defaultRequestQueueId')]
     build_number: Annotated[str | None, Field(alias='buildNumber')] = None
-    container_url: Annotated[str, Field(alias='containerUrl')]
+    container_url: Annotated[str | None, Field(alias='containerUrl')] = None
     is_container_server_ready: Annotated[bool | None, Field(alias='isContainerServerReady')] = None
     git_branch_name: Annotated[str | None, Field(alias='gitBranchName')] = None
     usage: Annotated[ActorRunUsage | None, Field(alias='usage')] = None
     usage_total_usd: Annotated[float | None, Field(alias='usageTotalUsd')] = None
-    usage_usd: Annotated[ActorRunUsage | None, Field(alias='usageUsd')] = None
+    usage_usd: Annotated[ActorRunUsageUsd | None, Field(alias='usageUsd')] = None
     pricing_info: Annotated[
         FreeActorPricingInfo
         | FlatPricePerMonthActorPricingInfo
@@ -132,43 +280,4 @@ class ActorRun(BaseModel):
         dict[str, int] | None,
         Field(alias='chargedEventCounts'),
     ] = None
-
-
-class FreeActorPricingInfo(BaseModel):
-    pricing_model: Annotated[Literal['FREE'], Field(alias='pricingModel')]
-
-
-class FlatPricePerMonthActorPricingInfo(BaseModel):
-    pricing_model: Annotated[Literal['FLAT_PRICE_PER_MONTH'], Field(alias='pricingModel')]
-    trial_minutes: Annotated[int | None, Field(alias='trialMinutes')] = None
-    price_per_unit_usd: Annotated[Decimal, Field(alias='pricePerUnitUsd')]
-
-
-class PricePerDatasetItemActorPricingInfo(BaseModel):
-    pricing_model: Annotated[Literal['PRICE_PER_DATASET_ITEM'], Field(alias='pricingModel')]
-    unit_name: Annotated[str | None, Field(alias='unitName')] = None
-    price_per_unit_usd: Annotated[Decimal, Field(alias='pricePerUnitUsd')]
-
-
-class ActorChargeEvent(BaseModel):
-    event_price_usd: Annotated[Decimal, Field(alias='eventPriceUsd')]
-    event_title: Annotated[str, Field(alias='eventTitle')]
-    event_description: Annotated[str | None, Field(alias='eventDescription')] = None
-
-
-class PricingPerEvent(BaseModel):
-    actor_charge_events: Annotated[dict[str, ActorChargeEvent], Field(alias='actorChargeEvents')]
-
-
-class PayPerEventActorPricingInfo(BaseModel):
-    pricing_model: Annotated[Literal['PAY_PER_EVENT'], Field(alias='pricingModel')]
-    pricing_per_event: Annotated[PricingPerEvent, Field(alias='pricingPerEvent')]
-    minimal_max_total_charge_usd: Annotated[Decimal | None, Field(alias='minimalMaxTotalChargeUsd')] = None
-
-
-PricingModel: TypeAlias = Literal[
-    'FREE',
-    'FLAT_PRICE_PER_MONTH',
-    'PRICE_PER_DATASET_ITEM',
-    'PAY_PER_EVENT',
-]
+    metamorphs: Annotated[list[Metamorph] | None, Field(alias='metamorphs')] = None
diff --git a/src/apify/storage_clients/_apify/_models.py b/src/apify/storage_clients/_apify/_models.py
@@ -26,7 +26,7 @@ class ApifyKeyValueStoreMetadata(KeyValueStoreMetadata):
 class ProlongRequestLockResponse(BaseModel):
     """Response to prolong request lock calls."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     lock_expires_at: Annotated[datetime, Field(alias='lockExpiresAt')]
 
@@ -39,7 +39,7 @@ class RequestQueueHead(BaseModel):
     including metadata about the queue's state and lock information for the requests.
     """
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     limit: Annotated[int | None, Field(alias='limit', default=None)]
     """The maximum number of requests that were requested from the queue."""
@@ -66,7 +66,7 @@ class KeyValueStoreKeyInfo(BaseModel):
     Only internal structure.
     """
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     key: Annotated[str, Field(alias='key')]
     size: Annotated[int, Field(alias='size')]
@@ -78,7 +78,7 @@ class KeyValueStoreListKeysPage(BaseModel):
     Only internal structure.
     """
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     count: Annotated[int, Field(alias='count')]
     limit: Annotated[int, Field(alias='limit')]
@@ -108,7 +108,7 @@ class CachedRequest(BaseModel):
 
 
 class RequestQueueStats(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     delete_count: Annotated[int, Field(alias='deleteCount', default=0)]
     """"The number of request queue deletes."""
diff --git a/tests/e2e/test_actor_call_timeouts.py b/tests/e2e/test_actor_call_timeouts.py
