docs

Apify Go client documentation

This directory documents the public API of the Apify Go client, organized by resource. Each page lists the available methods with their parameters and short, runnable snippets. For an overview, configuration, error handling, and the full resource table, see the top-level README.

All snippets assume a configured client and a context:

client := apify.NewClient(apify.WithToken("my-api-token"))
ctx := context.Background()

NewClient takes functional options; authentication is supplied via apify.WithToken. It does not read APIFY_TOKEN (or any other environment variable) automatically. Read it yourself if you want that, e.g. apify.NewClient(apify.WithToken(os.Getenv("APIFY_TOKEN"))). Pass additional options for non-default settings (base URL, retries, timeout, user-agent suffix, custom HTTP backend).

WithToken is optional. Omit it to create an unauthenticated client that can still call the few endpoints that require no token. For example, resolving and fetching a public Actor's default build needs only the public Actor ID (no build ID and no token):

publicClient := apify.NewClient()
buildClient, err := publicClient.Actor("apify/hello-world").DefaultBuild(ctx, nil)
if err != nil {
	log.Fatal(err)
}
build, ok, err := buildClient.Get(ctx)

A runnable version is in examples/public_build_no_token. Account-scoped endpoints and anything that reads or writes your resources require a token.

Methods that fetch a single resource return a (value, ok, error) triple: a missing resource is reported by ok == false rather than an error. API failures are returned as *apify.APIError (see error handling).

Setting optional fields — apify.Ptr

Optional option-struct fields are pointer-typed (so "unset" is distinguishable from a zero value). The exported generic helper apify.Ptr[T](v T) *T sets them inline without a named local:

page, err := client.Actors().List(ctx, apify.ActorListOptions{
	My:    apify.Ptr(true),
	Limit: apify.Ptr(int64(10)),
})

Common list options — apify.ListOptions

Most List methods (builds, runs, tasks, schedules, webhooks, Actor versions) take the shared apify.ListOptions, which carries the standard pagination/ordering controls. All fields are optional pointers; leave a field nil to use the API default. Use apify.Ptr to set them inline.

Field	Type	Meaning
Offset	*int64	Number of items to skip from the start of the list.
Limit	*int64	Maximum number of items to return.
Desc	*bool	If true, return items newest-first.

page, err := client.Builds().List(ctx, apify.ListOptions{
	Limit: apify.Ptr(int64(50)),
	Desc:  apify.Ptr(true),
})

Collections with extra filters use a dedicated options type instead of (or in addition to) ListOptions: ActorListOptions (Actors), StorageListOptions (datasets/key-value stores/request queues), StoreListOptions (the Store), and RunListOptions (runs, passed alongside ListOptions). Each is documented on its resource page.

Pagination

List/iterate methods return apify.PaginationList[T], one page plus the API's pagination metadata:

Field	Type	Meaning
Items	[]T	The items in this page.
Total	int64	Total items available across all pages.
Count	int64	Number of entries on this page. On a page of dataset items, the number of dataset rows the API scanned for it, or the number of items returned when that is larger: filters (Clean, SkipEmpty, SkipHidden) can leave it above len(Items). The next page starts at Offset + min(Count, Limit); the cap matters only with Unwind, which can return more items than the rows scanned.
Offset	int64	Items skipped before this page.
Limit	int64	Max items the API would return for this request.
Desc	bool	Whether items are in descending order.

The Iterate methods fetch as many pages as needed, so you do not manage offsets or limits. Limit caps the total number of items, and chunkSize caps the number of items per API call. Without chunkSize, each call gets the API's default page size, capped by Limit. Dataset items have no default limit, so iterating IterateItems without chunkSize loads the whole dataset, or all Limit items, in one response. To iterate a large dataset, pass chunkSize.

Total can lag right after a write. The API computes the count asynchronously, so immediately after a PushItems (or other write) Total may not yet include the new items. Re-read after a short delay if you need an exact post-write total.

The collection List methods (Actors, builds, runs, tasks, schedules, webhooks, datasets, key-value stores, request queues) return PaginationList[T]. The within-storage listers use their own page/head containers instead, because the underlying API endpoints paginate differently: KeyValueStoreClient.ListKeys returns KeyValueStoreKeysPage (key-based pagination) and RequestQueueClient.ListHead returns RequestQueueHead. Both are documented on the storages page.

Pages

• Actors — Actors, versions, environment variables.
• Server Actors — Sending requests to Server Actors (formerly Actor Standby).
• Builds — Actor builds.
• Runs — Actor runs, their default storages, log redirection and live iteration of dataset items.
• Tasks — Actor tasks.
• Storages — Datasets, key-value stores, request queues.
• Schedules — Schedules.
• Webhooks — Webhooks and webhook dispatches.
• Misc — Apify Store, users, logs.

Examples

Full runnable programs are in ../examples and are tested in CI.