From 060d173cb564628755898bc03dbff773e5af8100 Mon Sep 17 00:00:00 2001 From: mhamas Date: Mon, 14 Aug 2023 15:11:00 +0200 Subject: [PATCH 1/4] feat: explain usage usd on run and build objects --- sources/platform/api_v2/api_v2_reference.apib | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/sources/platform/api_v2/api_v2_reference.apib b/sources/platform/api_v2/api_v2_reference.apib index 070093497c..7895ef948d 100644 --- a/sources/platform/api_v2/api_v2_reference.apib +++ b/sources/platform/api_v2/api_v2_reference.apib @@ -863,6 +863,10 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. +This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the build. If +you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the +services the build consumed. + + Parameters + buildId: `soSkq9ekdmfOslopH` (string, required) - ID of the build you want to get, found in the build's `Info` tab. @@ -1293,7 +1297,9 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. +This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. If +you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the +services the run consumed. + Parameters @@ -2185,7 +2191,9 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. +This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. If +you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the +services the run consumed. + Parameters @@ -2357,6 +2365,10 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. +This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the build. If +you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the +services the build consumed. + + Parameters + buildId: `soSkq9ekdmfOslopH` (string, required) - ID of the build you want to get, found in the build's `Info` tab. From 53b54b894e708068ce0b4f57b3aa7b2197fbb5a5 Mon Sep 17 00:00:00 2001 From: Matej Hamas Date: Mon, 14 Aug 2023 16:32:27 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: TheoVasilis <98097738+TheoVasilis@users.noreply.github.com> --- sources/platform/api_v2/api_v2_reference.apib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sources/platform/api_v2/api_v2_reference.apib b/sources/platform/api_v2/api_v2_reference.apib index 7895ef948d..43a86c19c4 100644 --- a/sources/platform/api_v2/api_v2_reference.apib +++ b/sources/platform/api_v2/api_v2_reference.apib @@ -863,7 +863,7 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the build. If +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. If you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the services the build consumed. @@ -1297,7 +1297,7 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. If +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. If you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the services the run consumed. @@ -2191,7 +2191,7 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the run. If +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. If you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the services the run consumed. @@ -2365,7 +2365,7 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. -This endpoint does not require the authentication token, the calls are authenticated using a hard-to-guess ID of the build. If +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. If you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the services the build consumed. From cd0dbd49d79780b70ed7c67558fc73ff5f85159f Mon Sep 17 00:00:00 2001 From: mhamas Date: Wed, 16 Aug 2023 10:17:30 +0200 Subject: [PATCH 3/4] improve docs --- .../actors/running/usage_and_resources.md | 4 +++ sources/platform/api_v2/api_v2_reference.apib | 32 ++++++++++++------- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/sources/platform/actors/running/usage_and_resources.md b/sources/platform/actors/running/usage_and_resources.md index 55107929a1..d30a71bb3b 100644 --- a/sources/platform/actors/running/usage_and_resources.md +++ b/sources/platform/actors/running/usage_and_resources.md @@ -88,6 +88,10 @@ When you run an Actor it generates platform usage that's charged towards the use - **Proxy costs**: Residential or SERP proxy usage. - **Storage operations**: Read, write, and other operations towards key-value store, dataset, and request queue. +The platform usage can be represented either in raw units (e.g. gigabytes for data transfer, or number of writes for dataset operations), or in the dollar equivalents. +Note that for technical reasons, every time you see the usage in dollars on a specific historical Actor run or build in the API or the Apify Console, your current service pricing is used to compute the dollar amount, +and hence it should be used only for informative purposes. + > For detailed information, FAQ, and, pricing see the [platform pricing page](https://apify.com/pricing/actors). diff --git a/sources/platform/api_v2/api_v2_reference.apib b/sources/platform/api_v2/api_v2_reference.apib index 43a86c19c4..a2b057c464 100644 --- a/sources/platform/api_v2/api_v2_reference.apib +++ b/sources/platform/api_v2/api_v2_reference.apib @@ -391,6 +391,10 @@ Note that for all the API endpoints that accept the `actorId` parameter to speci you can pass either the actor ID (e.g. `HG7ML7M8z78YcAPEB`) or a tilde-separated username of the actor owner and the actor name (e.g. `janedoe~my-actor`). +Some of the API endpoints return runs objects. Note that if any such run object contains usage in dollars, your effective unit pricing at the time of query +has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. You can learn more +about platform usage in the documentation. + ## Actor collection [/v2/acts{?token,offset,limit,desc,my}] + Parameters @@ -863,9 +867,7 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. -This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. If -you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the -services the build consumed. +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. + Parameters @@ -1297,9 +1299,7 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. If -you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the -services the run consumed. +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. + Parameters @@ -1469,6 +1469,10 @@ Note that for all the API endpoints that accept the `actorTaskId` parameter to s you can pass either the task ID (e.g. `HG7ML7M8z78YcAPEB`) or a tilde-separated username of the task's owner and the task's name (e.g. `janedoe~my-task`). +Some of the API endpoints return runs objects. Note that if any such run object contains usage in dollars, your effective unit pricing at the time of query +has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. You can learn more +about platform usage in the documentation. + ## Task collection [/v2/actor-tasks{?token,offset,limit,desc}] + Parameters @@ -2091,6 +2095,10 @@ In order to save new items to the dataset, send HTTP POST request with JSON payl The API endpoints described in this section enable you to manage Apify actor runs. +Note that if any returned run object contains usage in dollars, your effective unit pricing at the time of query +has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. +You can learn more about platform usage in the documentation. + ## Run collection [/v2/actor-runs{?token,offset,limit,desc,status}] ### Get user runs list [GET] @@ -2191,9 +2199,7 @@ Gets an object that contains all the details about a specific run of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for actor run to complete. -This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. If -you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the -services the run consumed. +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the run. + Parameters @@ -2321,6 +2327,10 @@ you will also need to specify `isStatusMessageTerminal=true`. In the absence of The API endpoints described in this section enable you to manage Apify actor builds. +Note that if any returned build object contains usage in dollars, your effective unit pricing at the time of query +has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. +You can learn more about platform usage in the documentation. + ## Build collection [/v2/actor-builds{?token,offset,limit,desc}] + Parameters @@ -2365,9 +2375,7 @@ Gets an object that contains all the details about a specific build of an actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an actor build to finish. -This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. If -you pass the authentication token, your effective pricing at the time of query will be used to compute the dollar values of the -services the build consumed. +This endpoint does not require the authentication token. The calls are authenticated using a hard-to-guess ID of the build. + Parameters From 12931aced2775be05fd34fc9c4f61deebd9fae70 Mon Sep 17 00:00:00 2001 From: Matej Hamas Date: Wed, 16 Aug 2023 16:45:50 +0200 Subject: [PATCH 4/4] Update sources/platform/actors/running/usage_and_resources.md Co-authored-by: TheoVasilis <98097738+TheoVasilis@users.noreply.github.com> --- sources/platform/actors/running/usage_and_resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/running/usage_and_resources.md b/sources/platform/actors/running/usage_and_resources.md index d30a71bb3b..131ec02ba6 100644 --- a/sources/platform/actors/running/usage_and_resources.md +++ b/sources/platform/actors/running/usage_and_resources.md @@ -89,7 +89,7 @@ When you run an Actor it generates platform usage that's charged towards the use - **Storage operations**: Read, write, and other operations towards key-value store, dataset, and request queue. The platform usage can be represented either in raw units (e.g. gigabytes for data transfer, or number of writes for dataset operations), or in the dollar equivalents. -Note that for technical reasons, every time you see the usage in dollars on a specific historical Actor run or build in the API or the Apify Console, your current service pricing is used to compute the dollar amount, +Note that for technical reasons, every time you see the usage in dollars on a specific historical Actor run or build in the API or Apify Console, your current service pricing is used to compute the dollar amount, and hence it should be used only for informative purposes. > For detailed information, FAQ, and, pricing see the [platform pricing page](https://apify.com/pricing/actors).