Skip to content
getgeolens.com
GeoLens Docs

Trigger Backfill

POST
/admin/backfill-embeddings/
 
curl --request POST \
  --url 'https://example.com/admin/backfill-embeddings/?force=false&all_tenants=false' \
  --header 'Authorization: Bearer <token>'

Queue semantic-search embedding generation for records (admin only).

Pass ?force=true to regenerate every record and replace its stored vectors. Without it, the run embeds only records that lack a current-model embedding.

The run covers the calling tenant’s records. In a multi-tenant deployment the embedding model and width are shared by every tenant, so a change leaves each tenant to regenerate. Pass ?all_tenants=true to also queue a run for every other registered tenant; there it needs manage_tenants instead of manage_users, and other_tenants reports each run. When the calling tenant already has a run in flight, the status is already_running, job_id is that run (null when the caller may not read it) and the other tenants are still queued. This request did not queue that run and it may predate the change, so run the backfill again once it ends. A single-tenant deployment ignores the flag.

The run happens on the job queue because a full regeneration can exceed request timeouts. This endpoint returns the job id; poll GET /jobs/{job_id} for the outcome.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “ Query Parameters ”
force
Force
boolean
all_tenants
All Tenants
boolean

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Successful Response

Media type application/json
BackfillResponse

Acknowledgement that a backfill run was queued.

The response carries no counts because the work runs asynchronously. Poll GET /jobs/{job_id} for status.

object
job_id
required
Any of:
string format: uuid
status
required
Status

‘pending’ when this request queued job_id. ‘already_running’ when an all_tenants request found a run in flight in the calling tenant; job_id is then that run, which this request did not queue. Run the backfill again once it ends.

string
other_tenants
Other Tenants

Runs queued for the other tenants by an all_tenants request in a multi-tenant deployment. Empty otherwise.

Array<object>
BackfillTenantRun

What an all-tenant backfill request did for one other tenant.

object
tenant_id
required
Tenant Id

The tenant the run was queued for.

string format: uuid
job_id
required
Any of:
string format: uuid
status
required
Status

‘pending’ when a run was queued, ‘already_running’ when that tenant already had one in flight, ‘not_queued’ when queueing failed.

string
Allowed values: pending already_running not_queued

Example 

{
  "other_tenants": [
    {
      "status": "pending"
    }
  ]
}

400

Section titled “ 400 ”

Bad request — invalid query parameters or payload

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Section titled “ 401 ”

Unauthorized — missing or invalid credentials

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

403

Section titled “ 403 ”

Forbidden — caller lacks access to this resource

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Section titled “ 404 ”

Not found

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

409

Section titled “ 409 ”

Conflict — resource state prevents the operation

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Section titled “ 422 ”

Validation error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Section titled “ 429 ”

Too many requests — retry after the advertised interval

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Section titled “ Headers ”
Retry-After
integer

Seconds until the request may be retried

500

Section titled “ 500 ”

Internal server error

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Section titled “ 503 ”

Service unavailable — the background job queue could not be reached

Media type application/problem+json
ProblemDetail
object
type
Type
string
default: about:blank
title
required
Title
string
status
required
Status
integer
detail
required
Any of:
string

Example 

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}
Privacy Apache 2.0 getgeolens.com