list | Botbye | Documentation

Retrieves a paginated list of captcha tasks issued for a project, one row per task, with what became of it.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/captcha-records

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project to retrieve captcha task records for

Query Parameters

Pagination: cursor-based (cursor). By default a page holds 20 records, max 100.
Filtering: where accepts task_id, created_at, updated_at, solved_at, status, visitor_id, account_id and custom_fields. A custom_fields condition names its key. A status condition names the state (SOLVED), not a number, and in takes the list either as ['SOLVED','REDEEMED'] or as SOLVED,REDEEMED. Predicates is_null, is_not_null, has_any and has_all are not accepted.
Ordering: order_by accepts created_at and task_id; records are returned newest first by default.
Total: total=true adds the number of matching tasks to pageInfo.

Response Structure

Cursor-based pagination. Each node is one captcha task:

Field	Type	Description
`taskId`	string	The captcha task id, as handed to the browser and later presented with the protected request
`createdAt`	string	Timestamp (epoch millis) the task was issued
`status`	string	`ISSUED`, `SOLVE_FAILED`, `SOLVED`, `EXPIRED`, `REDEEMED` or `REPLAYED` — the furthest state the task reached
`updatedAt`	string	Timestamp (epoch millis) of the last state change; absent while the task is only issued
`solvedAt`	string	Timestamp (epoch millis) the task was solved; absent while it is unsolved
`visitorId`	string	Visitor that redeemed the task; empty unless the task was redeemed with a verified token
`accountId`	string	End-user account that redeemed the task; empty under the same condition
`customFields`	object	The fields your integration passed when the task was issued

pageInfo carries hasPreviousPage, hasNextPage, startCursor, endCursor and total (the number of matching tasks).

Use Cases

Support: show a user’s captcha history when they report being unable to pass a challenge.
Integration debugging: follow one of your own identifiers, passed as a custom field, from issue to redemption.
Abuse review: see how a visitor or account has been solving captchas.

Accepted permissions Project → Events → View → Captcha

Token scope Request View

# Get Captcha Task Records Retrieves a paginated list of captcha tasks issued for a project, one row per task, with what became of it. ## Endpoint ``` GET {base_url}/api/v1/{account_id}/projects/{project_id}/captcha-records ``` ## Authentication Requires API key authentication: ``` Authorization: Bearer {api_key} ``` ## Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account_id` | string | Yes | Your unique BotBye account identifier | | `project_id` | string | Yes | The project to retrieve captcha task records for | ## Query Parameters - **Pagination**: cursor-based (`cursor`). By default a page holds 20 records, max 100. - **Filtering**: `where` accepts `task_id`, `created_at`, `updated_at`, `solved_at`, `status`, `visitor_id`, `account_id` and `custom_fields`. A `custom_fields` condition names its key. A `status` condition names the state (`SOLVED`), not a number, and `in` takes the list either as `['SOLVED','REDEEMED']` or as `SOLVED,REDEEMED`. Predicates `is_null`, `is_not_null`, `has_any` and `has_all` are not accepted. - **Ordering**: `order_by` accepts `created_at` and `task_id`; records are returned newest first by default. - **Total**: `total=true` adds the number of matching tasks to `pageInfo`. ## Response Structure Cursor-based pagination. Each `node` is one captcha task: | Field | Type | Description | | --- | --- | --- | | `taskId` | string | The captcha task id, as handed to the browser and later presented with the protected request | | `createdAt` | string | Timestamp (epoch millis) the task was issued | | `status` | string | `ISSUED`, `SOLVE_FAILED`, `SOLVED`, `EXPIRED`, `REDEEMED` or `REPLAYED` — the furthest state the task reached | | `updatedAt` | string | Timestamp (epoch millis) of the last state change; absent while the task is only issued | | `solvedAt` | string | Timestamp (epoch millis) the task was solved; absent while it is unsolved | | `visitorId` | string | Visitor that redeemed the task; empty unless the task was redeemed with a verified token | | `accountId` | string | End-user account that redeemed the task; empty under the same condition | | `customFields` | object | The fields your integration passed when the task was issued | **pageInfo** carries `hasPreviousPage`, `hasNextPage`, `startCursor`, `endCursor` and `total` (the number of matching tasks). ## Use Cases - **Support**: show a user's captcha history when they report being unable to pass a challenge. - **Integration debugging**: follow one of your own identifiers, passed as a custom field, from issue to redemption. - **Abuse review**: see how a visitor or account has been solving captchas. > **Accepted permissions** > `Project → Events → View → Captcha` > > **Token scope** > `Request View`

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Personal access token. Create it in your BotBye account under **Profile → Personal Access Tokens**, tick the scopes the endpoints you call require (see each endpoint's **Token scope**), and send the token in the `X-Api-Key` request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired

project_idstringRequired

Query parameters

cursorstringOptional

(Optional): a cursor for pagination.

after (string): Pointer to the item after which the items are to be retrieved.
before (string): Pointer to the item before which the items are to be retrieved.

(Optional): a cursor for pagination. - `after` (string): Pointer to the item after which the items are to be retrieved. - `before` (string): Pointer to the item before which the items are to be retrieved.

wherestringOptional

(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes).

predicate (string): The filtering condition (e.g., gte, lte, eq for a leaf or and, or for a branch). Possible values [[#Predicate]]
opearands (string): A list of nested conditions (used only for branches, such as and, or).
fieldPath (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list).
value (string): The value to compare against the field (used only for a leaf).

(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes). - `predicate` (string): The filtering condition (e.g., `gte`, `lte`, `eq` for a leaf or `and`, `or` for a branch). Possible values [[#Predicate]] - `opearands` (string): A list of nested conditions (used only for branches, such as `and`, `or`). - `fieldPath` (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list). - `value` (string): The value to compare against the field (used only for a leaf).

order_bystringOptional

(Optional): property by which to order by.

fieldPath (string): name of order field.
direction (string): ASC or DESC

(Optional): property by which to order by. - `fieldPath` (string): name of order field. - `direction` (string): `ASC` or `DESC`

totalstringOptional

(Optional): when true, pageInfo.total carries the number of matching tasks.

Response headers

Content-Lengthinteger

ConnectionstringOptional

Response

success

edgeslist of objects

pageInfoobject

attributesobject

Errors

400

Bad Request Error

Retrieves a paginated list of captcha tasks issued for a project, one row per task, with what became of it.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/captcha-records

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project to retrieve captcha task records for

Query Parameters

Pagination: cursor-based (cursor). By default a page holds 20 records, max 100.
Filtering: where accepts task_id, created_at, updated_at, solved_at, status, visitor_id, account_id and custom_fields. A custom_fields condition names its key. A status condition names the state (SOLVED), not a number, and in takes the list either as ['SOLVED','REDEEMED'] or as SOLVED,REDEEMED. Predicates is_null, is_not_null, has_any and has_all are not accepted.
Ordering: order_by accepts created_at and task_id; records are returned newest first by default.
Total: total=true adds the number of matching tasks to pageInfo.

Response Structure

Cursor-based pagination. Each node is one captcha task:

Field	Type	Description
`taskId`	string	The captcha task id, as handed to the browser and later presented with the protected request
`createdAt`	string	Timestamp (epoch millis) the task was issued
`status`	string	`ISSUED`, `SOLVE_FAILED`, `SOLVED`, `EXPIRED`, `REDEEMED` or `REPLAYED` — the furthest state the task reached
`updatedAt`	string	Timestamp (epoch millis) of the last state change; absent while the task is only issued
`solvedAt`	string	Timestamp (epoch millis) the task was solved; absent while it is unsolved
`visitorId`	string	Visitor that redeemed the task; empty unless the task was redeemed with a verified token
`accountId`	string	End-user account that redeemed the task; empty under the same condition
`customFields`	object	The fields your integration passed when the task was issued

pageInfo carries hasPreviousPage, hasNextPage, startCursor, endCursor and total (the number of matching tasks).

Use Cases

Support: show a user’s captcha history when they report being unable to pass a challenge.
Integration debugging: follow one of your own identifiers, passed as a custom field, from issue to redemption.
Abuse review: see how a visitor or account has been solving captchas.

Accepted permissions Project → Events → View → Captcha

Token scope Request View