Skip to content

Commit aca3484

Browse files
Pijukatelclaude
Pijukatel
and
claude
committed
docs: document runs/last redispatch sub-paths in OpenAPI spec
The `/v2/acts/{actorId}/runs/last` and `/v2/actor-tasks/{actorTaskId}/runs/last` endpoints redispatch to canonical storage and run-action endpoints after resolving the last run. Previously these sub-paths were only described in prose. This commit adds them as proper OpenAPI path entries for both Actor and actor task namespaces: - log - dataset, dataset/items - key-value-store, key-value-store/keys, key-value-store/records/{recordKey} - request-queue, request-queue/requests, request-queue/requests/{requestId}, request-queue/head - abort, metamorph, reboot Also adds the missing `waitForFinish` query parameter to both base `runs/last` endpoints, which was causing "Unknown query parameter" validation errors. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 7646531 commit aca3484

33 files changed

Lines changed: 1496 additions & 32 deletions

File tree

‎apify-api/openapi/components/parameters/actorId.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
name: actorId
2+
in: path
3+
description: Actor ID or a tilde-separated owner's username and Actor name.
4+
required: true
5+
style: simple
6+
schema:
7+
type: string
8+
example: janedoe~my-actor

‎apify-api/openapi/components/parameters/actorTaskId.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
name: actorTaskId
2+
in: path
3+
description: Task ID or a tilde-separated owner's username and Actor task name.
4+
required: true
5+
style: simple
6+
schema:
7+
type: string
8+
example: janedoe~my-task

‎apify-api/openapi/components/parameters/runs-last/status.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
name: status
2+
in: query
3+
description: Filter for the run status. Only the most recent run with this status is used.
4+
style: form
5+
explode: true
6+
schema:
7+
type: string
8+
example: SUCCEEDED

‎apify-api/openapi/components/parameters/runs-last/waitForFinish.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: waitForFinish
2+
in: query
3+
description: |
4+
The maximum number of seconds the server waits for the run to finish. By
5+
default it is `0`, the maximum value is `60`. <!--
6+
MAX_ACTOR_JOB_ASYNC_WAIT_SECS -->
7+
If the run finishes in time then the returned run object will have a terminal status (e.g. `SUCCEEDED`),
8+
otherwise it will have a transitional status (e.g. `RUNNING`).
9+
style: form
10+
explode: true
11+
schema:
12+
type: number
13+
format: double

‎apify-api/openapi/openapi.yaml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -514,6 +514,32 @@ paths:
514514
$ref: "paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml"
515515
"/v2/acts/{actorId}/runs/last":
516516
$ref: "paths/actors/acts@{actorId}@runs@last.yaml"
517+
"/v2/acts/{actorId}/runs/last/log":
518+
$ref: "paths/actors/acts@{actorId}@runs@last@log.yaml"
519+
"/v2/acts/{actorId}/runs/last/dataset":
520+
$ref: "paths/actors/acts@{actorId}@runs@last@dataset.yaml"
521+
"/v2/acts/{actorId}/runs/last/dataset/items":
522+
$ref: "paths/actors/acts@{actorId}@runs@last@dataset@items.yaml"
523+
"/v2/acts/{actorId}/runs/last/key-value-store":
524+
$ref: "paths/actors/acts@{actorId}@runs@last@key-value-store.yaml"
525+
"/v2/acts/{actorId}/runs/last/key-value-store/keys":
526+
$ref: "paths/actors/acts@{actorId}@runs@last@key-value-store@keys.yaml"
527+
"/v2/acts/{actorId}/runs/last/key-value-store/records/{recordKey}":
528+
$ref: "paths/actors/acts@{actorId}@runs@last@key-value-store@records@{recordKey}.yaml"
529+
"/v2/acts/{actorId}/runs/last/request-queue":
530+
$ref: "paths/actors/acts@{actorId}@runs@last@request-queue.yaml"
531+
"/v2/acts/{actorId}/runs/last/request-queue/requests":
532+
$ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests.yaml"
533+
"/v2/acts/{actorId}/runs/last/request-queue/requests/{requestId}":
534+
$ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests@{requestId}.yaml"
535+
"/v2/acts/{actorId}/runs/last/request-queue/head":
536+
$ref: "paths/actors/acts@{actorId}@runs@last@request-queue@head.yaml"
537+
"/v2/acts/{actorId}/runs/last/abort":
538+
$ref: "paths/actors/acts@{actorId}@runs@last@abort.yaml"
539+
"/v2/acts/{actorId}/runs/last/metamorph":
540+
$ref: "paths/actors/acts@{actorId}@runs@last@metamorph.yaml"
541+
"/v2/acts/{actorId}/runs/last/reboot":
542+
$ref: "paths/actors/acts@{actorId}@runs@last@reboot.yaml"
517543
"/v2/acts/{actorId}/runs/{runId}":
518544
$ref: "paths/actors/acts@{actorId}@runs@{runId}.yaml"
519545
"/v2/acts/{actorId}/runs/{runId}/abort":
@@ -536,6 +562,32 @@ paths:
536562
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml"
537563
"/v2/actor-tasks/{actorTaskId}/runs/last":
538564
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last.yaml"
565+
"/v2/actor-tasks/{actorTaskId}/runs/last/log":
566+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@log.yaml"
567+
"/v2/actor-tasks/{actorTaskId}/runs/last/dataset":
568+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@dataset.yaml"
569+
"/v2/actor-tasks/{actorTaskId}/runs/last/dataset/items":
570+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@dataset@items.yaml"
571+
"/v2/actor-tasks/{actorTaskId}/runs/last/key-value-store":
572+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@key-value-store.yaml"
573+
"/v2/actor-tasks/{actorTaskId}/runs/last/key-value-store/keys":
574+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@key-value-store@keys.yaml"
575+
"/v2/actor-tasks/{actorTaskId}/runs/last/key-value-store/records/{recordKey}":
576+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@key-value-store@records@{recordKey}.yaml"
577+
"/v2/actor-tasks/{actorTaskId}/runs/last/request-queue":
578+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@request-queue.yaml"
579+
"/v2/actor-tasks/{actorTaskId}/runs/last/request-queue/requests":
580+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@request-queue@requests.yaml"
581+
"/v2/actor-tasks/{actorTaskId}/runs/last/request-queue/requests/{requestId}":
582+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@request-queue@requests@{requestId}.yaml"
583+
"/v2/actor-tasks/{actorTaskId}/runs/last/request-queue/head":
584+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@request-queue@head.yaml"
585+
"/v2/actor-tasks/{actorTaskId}/runs/last/abort":
586+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@abort.yaml"
587+
"/v2/actor-tasks/{actorTaskId}/runs/last/metamorph":
588+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@metamorph.yaml"
589+
"/v2/actor-tasks/{actorTaskId}/runs/last/reboot":
590+
$ref: "paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@reboot.yaml"
539591
/v2/actor-runs:
540592
$ref: paths/actor-runs/actor-runs.yaml
541593
"/v2/actor-runs/{runId}":

‎apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last.yaml‎

Lines changed: 3 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -51,22 +51,9 @@ get:
5151
In order to save new items to the dataset, send HTTP POST request with JSON payload to the same URL.
5252
operationId: actorTask_runs_last_get
5353
parameters:
54-
- name: actorTaskId
55-
in: path
56-
description: Task ID or a tilde-separated owner's username and Actor task name.
57-
required: true
58-
style: simple
59-
schema:
60-
type: string
61-
example: janedoe~my-task
62-
- name: status
63-
in: query
64-
description: Filter for the run status.
65-
style: form
66-
explode: true
67-
schema:
68-
type: string
69-
example: SUCCEEDED
54+
- $ref: ../../components/parameters/actorTaskId.yaml
55+
- $ref: ../../components/parameters/runs-last/status.yaml
56+
- $ref: ../../components/parameters/runs-last/waitForFinish.yaml
7057
responses:
7158
"200":
7259
description: ""

‎apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@abort.yaml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
post:
2+
tags:
3+
- Actor tasks
4+
summary: Abort last run
5+
description: |
6+
Aborts the last actor task run. Redispatches to [Abort run](/api/v2/actor-run-abort-post).
7+
8+
Using the `status` query parameter you can ensure to only get a run with a certain status
9+
(e.g. `status=SUCCEEDED`). Only the most recent run with that status is used.
10+
operationId: actorTask_runs_last_abort_post
11+
parameters:
12+
- $ref: ../../components/parameters/actorTaskId.yaml
13+
- $ref: ../../components/parameters/runs-last/status.yaml
14+
- name: gracefully
15+
in: query
16+
description: |
17+
If true passed, the Actor run will abort gracefully.
18+
It will send `aborting` and `persistState` event into run and force-stop the run after 30 seconds.
19+
It is helpful in cases where you plan to resurrect the run later.
20+
style: form
21+
explode: true
22+
schema:
23+
type: boolean
24+
responses:
25+
"200":
26+
description: ""
27+
headers: {}
28+
content:
29+
application/json:
30+
schema:
31+
$ref: ../../components/schemas/actor-runs/RunResponse.yaml
32+
example:
33+
data:
34+
id: HG7ML7M8z78YcAPEB
35+
actId: HDSasDasz78YcAPEB
36+
userId: 7sT5jcggjjA9fNcxF
37+
startedAt: "2019-11-30T07:34:24.202Z"
38+
finishedAt: "2019-12-12T09:30:12.202Z"
39+
status: RUNNING
40+
statusMessage: Actor is running
41+
isStatusMessageTerminal: false
42+
meta:
43+
origin: WEB
44+
clientIp: 172.234.12.34
45+
userAgent: Mozilla/5.0 (iPad)
46+
stats:
47+
inputBodyLen: 240
48+
migrationCount: 0
49+
restartCount: 0
50+
resurrectCount: 0
51+
durationMillis: 26239
52+
runTimeSecs: 26.239
53+
metamorph: 0
54+
computeUnits: 0.0072886
55+
options:
56+
build: latest
57+
timeoutSecs: 300
58+
memoryMbytes: 1024
59+
diskMbytes: 2048
60+
buildId: 7sT5jcggjjA9fNcxF
61+
exitCode: 0
62+
generalAccess: RESTRICTED
63+
defaultKeyValueStoreId: eJNzqsbPiopwJcgGQ
64+
defaultDatasetId: wmKPijuyDnPZAPRMk
65+
defaultRequestQueueId: FL35cSF7jrxr3BY39
66+
"400":
67+
$ref: ../../components/responses/BadRequest.yaml
68+
deprecated: false

‎apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@dataset.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
get:
2+
tags:
3+
- Actor tasks
4+
summary: Get dataset for last run
5+
description: |
6+
Returns the default dataset of the last actor task run. Redispatches to
7+
[Get dataset](/api/v2/dataset-get).
8+
9+
Using the `status` query parameter you can ensure to only get a run with a certain status
10+
(e.g. `status=SUCCEEDED`). Only the most recent run with that status is used.
11+
operationId: actorTask_runs_last_dataset_get
12+
parameters:
13+
- $ref: ../../components/parameters/actorTaskId.yaml
14+
- $ref: ../../components/parameters/runs-last/status.yaml
15+
responses:
16+
"200":
17+
description: ""
18+
headers: {}
19+
content:
20+
application/json:
21+
schema:
22+
$ref: ../../components/schemas/datasets/DatasetResponse.yaml
23+
"400":
24+
$ref: ../../components/responses/BadRequest.yaml
25+
deprecated: false

‎apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@dataset@items.yaml‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
get:
2+
tags:
3+
- Actor tasks
4+
summary: Get dataset items for last run
5+
description: |
6+
Returns items from the default dataset of the last actor task run. Redispatches to
7+
[Get dataset items](/api/v2/dataset-items-get). Supports the same query parameters.
8+
9+
Using the `status` query parameter you can ensure to only get a run with a certain status
10+
(e.g. `status=SUCCEEDED`). Only the most recent run with that status is used.
11+
operationId: actorTask_runs_last_dataset_items_get
12+
parameters:
13+
- $ref: ../../components/parameters/actorTaskId.yaml
14+
- $ref: ../../components/parameters/runs-last/status.yaml
15+
- name: format
16+
in: query
17+
description: Format of the results, possible values are json, jsonl, csv, html, xlsx, xml and rss.
18+
style: form
19+
explode: true
20+
schema:
21+
type: string
22+
default: json
23+
- name: clean
24+
in: query
25+
description: If true, returns only non-empty items and skips hidden fields.
26+
style: form
27+
explode: true
28+
schema:
29+
type: boolean
30+
- name: offset
31+
in: query
32+
description: Number of items that should be skipped at the start.
33+
style: form
34+
explode: true
35+
schema:
36+
type: number
37+
- name: limit
38+
in: query
39+
description: Maximum number of items to return.
40+
style: form
41+
explode: true
42+
schema:
43+
type: number
44+
- name: fields
45+
in: query
46+
description: Comma-separated list of fields to include in the results.
47+
style: form
48+
explode: true
49+
schema:
50+
type: string
51+
- name: omit
52+
in: query
53+
description: Comma-separated list of fields to omit from the results.
54+
style: form
55+
explode: true
56+
schema:
57+
type: string
58+
- name: unwind
59+
in: query
60+
description: Name of a field to unwind. If the field is an array, each element becomes a separate record.
61+
style: form
62+
explode: true
63+
schema:
64+
type: string
65+
- name: flatten
66+
in: query
67+
description: Comma-separated list of fields to flatten. Nested objects are merged into the parent.
68+
style: form
69+
explode: true
70+
schema:
71+
type: string
72+
- name: desc
73+
in: query
74+
description: If true, results are returned in descending order.
75+
style: form
76+
explode: true
77+
schema:
78+
type: boolean
79+
- name: attachment
80+
in: query
81+
description: If true, the response will be returned as a file attachment.
82+
style: form
83+
explode: true
84+
schema:
85+
type: boolean
86+
responses:
87+
"200":
88+
description: ""
89+
headers: {}
90+
content:
91+
application/json:
92+
schema:
93+
type: array
94+
items:
95+
type: object
96+
"400":
97+
$ref: ../../components/responses/BadRequest.yaml
98+
deprecated: false
99+
post:
100+
tags:
101+
- Actor tasks
102+
summary: Push items to dataset for last run
103+
description: |
104+
Pushes items to the default dataset of the last actor task run. Redispatches to
105+
[Push items](/api/v2/dataset-items-post).
106+
107+
Using the `status` query parameter you can ensure to only get a run with a certain status
108+
(e.g. `status=SUCCEEDED`). Only the most recent run with that status is used.
109+
operationId: actorTask_runs_last_dataset_items_post
110+
parameters:
111+
- $ref: ../../components/parameters/actorTaskId.yaml
112+
- $ref: ../../components/parameters/runs-last/status.yaml
113+
requestBody:
114+
required: true
115+
content:
116+
application/json:
117+
schema:
118+
type: array
119+
items:
120+
type: object
121+
responses:
122+
"201":
123+
description: Items were added.
124+
headers: {}
125+
"400":
126+
$ref: ../../components/responses/BadRequest.yaml
127+
deprecated: false

‎apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last@key-value-store.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
get:
2+
tags:
3+
- Actor tasks
4+
summary: Get key-value store for last run
5+
description: |
6+
Returns the default key-value store of the last actor task run. Redispatches to
7+
[Get store](/api/v2/key-value-store-get).
8+
9+
Using the `status` query parameter you can ensure to only get a run with a certain status
10+
(e.g. `status=SUCCEEDED`). Only the most recent run with that status is used.
11+
operationId: actorTask_runs_last_keyValueStore_get
12+
parameters:
13+
- $ref: ../../components/parameters/actorTaskId.yaml
14+
- $ref: ../../components/parameters/runs-last/status.yaml
15+
responses:
16+
"200":
17+
description: ""
18+
headers: {}
19+
content:
20+
application/json:
21+
schema:
22+
$ref: ../../components/schemas/key-value-stores/KeyValueStoreResponse.yaml
23+
"400":
24+
$ref: ../../components/responses/BadRequest.yaml
25+
deprecated: false

0 commit comments

Comments
 (0)