Skip to navigation
BotBye APIProtectionCAPTCHA Records

list

View as Markdown

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

ParameterTypeRequiredDescription
account_idstringYesYour unique BotBye account identifier
project_idstringYesThe 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:

FieldTypeDescription
taskIdstringThe captcha task id, as handed to the browser and later presented with the protected request
createdAtstringTimestamp (epoch millis) the task was issued
statusstringISSUED, SOLVE_FAILED, SOLVED, EXPIRED, REDEEMED or REPLAYED — the furthest state the task reached
updatedAtstringTimestamp (epoch millis) of the last state change; absent while the task is only issued
solvedAtstringTimestamp (epoch millis) the task was solved; absent while it is unsolved
visitorIdstringVisitor that redeemed the task; empty unless the task was redeemed with a verified token
accountIdstringEnd-user account that redeemed the task; empty under the same condition
customFieldsobjectThe 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.

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.
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).
order_bystringOptional

(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