Docs
Open Lodol
DocumentationIntegrationsAPI

Algolia

App · Databases · 30 actions

Search, browse and filter the records in your Algolia indices; add, update and delete records one at a time or thousands at once; manage index settings, synonyms and merchandising rules; copy, move and delete indices; read Search Analytics; send view, click and purchase events; and get Recommend suggestions.

Actions

ActionWhat it does
Add or replace a recordAdd a record to an index, or replace a record whole by its object ID.
Add or replace recordsAdd up to 10,000 records to an index at once, replacing any whose objectID is already there.
Browse recordsRead every record in an index, or every record matching a query and filters, up to 1,000 at a time.
Clear an indexDelete every record in an index, keeping its settings, synonyms and rules.
Copy or move an indexCopy an index, or only its settings, synonyms or rules, to another index, or move (rename) it.
Delete a recordDelete a record from an index by its object ID.
Delete a ruleDelete a rule from an index by its ID.
Delete a synonymDelete a synonym from an index by its ID.
Delete an indexDelete an index with its records, settings, synonyms and rules.
Delete recordsDelete up to 10,000 records from an index by their object IDs.
Delete records by filterDelete every record matching a filter, like category:discontinued or stock = 0, and say how many matched.
Get a recordRetrieve one record from an index by its object ID.
Get index settingsGet an index's settings, such as its searchable attributes, attributes for faceting and ranking, under Algolia's names.
Get recommendationsGet records Algolia Recommend suggests: related to a record, frequently bought with it, looking like it, or trending.
Get recordsRetrieve several records from an index by their object IDs, up to 10,000.
Get search countCount the searches on an index over a date range, in total and day by day, from Algolia Analytics.
Get searches without resultsGet the most frequent searches on an index that found nothing, over a date range, from Algolia Analytics: a list of what people want and can't find.
Get top searchesGet an index's most frequent searches over a date range from Algolia Analytics, with click and conversion rates when you send click events.
List indicesList the indices in your Algolia application, with their record counts and sizes.
Save a ruleAdd or replace a rule that pins records to the top of a search, hides records, applies filters or returns banner data: for searches matching a query, or for every search, and if you like only between two dates.
Save a synonymAdd or replace a synonym on an index: words that find each other (two-way), a term that also finds other words (one-way), an alternative correction, or a placeholder.
Search facet valuesFind the values of a faceted attribute that match some text, like the brands starting with 'app', with how many records hold each.
Search recordsSearch an index for records matching a query, narrowed with filters if you like (category:shoes AND price < 100), and count the values of facets such as brand.
Search rulesList an index's rules, the changes Algolia makes to some searches (pinned or hidden records, filters, banners), or those matching some text.
Search synonymsList an index's synonyms, or those containing some text, optionally of one type.
Send an eventTell Algolia a user viewed, clicked, added to cart or bought records, for Analytics, Recommend, Dynamic Re-Ranking and Personalization, for example a purchase when an order is paid.
Update a recordChange some attributes of a record and keep the rest.
Update index settingsChange some of an index's settings and keep the others, using Algolia's names, like {"attributesForFaceting": ["brand", "searchable(category)"]} or {"customRanking": ["desc(popularity)"]}.
Update recordsChange some attributes of up to 10,000 records at once, each given with its objectID, keeping their other attributes.
Wait for a taskWait until Algolia has applied a change, so the steps after it see it.

Add or replace a record

Add a record to an index, or replace a record whole by its object ID. Leave the object ID blank to let Algolia assign one. To change only some attributes, use Update a record.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
RecordrecordobjectRequired
The record's attributes and values, like name: Wireless Headphones and price: 79.99.
Object IDobject_idtext
The record's unique ID. A record with this ID is replaced whole; leave blank for Algolia to make one.

Outputs

object_idtext
The saved record's object ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the write
Example output
{
  "object_id": "eb-600",
  "task_id": 1753626438002,
  "updated_at": "2026-10-02T22:37:47.048Z"
}

Add or replace records

Add up to 10,000 records to an index at once, replacing any whose objectID is already there. Records without an objectID get one from Algolia. Waiting for the task ID returned waits for all of them.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
RecordsrecordslistRequired
The records, each an object of attributes, with an objectID to add or replace that record.

Outputs

countnumber
How many records were sent
object_idslist
The records' object IDs, in the order given
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "count": 6,
  "object_ids": [
    "hp-100",
    "hp-200",
    "sp-300",
    "kb-400",
    "ms-500",
    "9077987002"
  ],
  "task_id": 1753626425002
}

Browse records

Read every record in an index, or every record matching a query and filters, up to 1,000 at a time. Give the next cursor back to read the next batch, until has more is false. Unlike a search, a browse is not limited to the first 1,000 results. The API key needs the browse permission.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Search textquerytext
Text to search for. Leave empty to match every record, in the index's ranking order.
Filtersfilterstext
Algolia filter syntax, like category:shoes AND price < 100, or (brand:Acme OR brand:Zenith) AND NOT discontinued:true. A text attribute must be listed in the index's attributes for faceting to be filtered on; a filter on one that isn't is reported rather than matching nothing.
Attributes to returnattributes_to_retrievelist
Attribute names to return for each record, like name and price. Leave empty for every attribute the index returns. The objectID always comes back.
Records per batchhits_per_pagenumber
How many records to return at a time, from 1 to 1,000 (default 1,000).From 1 to 1000. Default: 1000.
Cursorcursortext
The next cursor an earlier Browse records returned, to read the batch after it. It carries that browse's search text, filters and batch size. Leave empty to start.

Outputs

countnumber
How many records this batch holds
has_moretrue/false
Whether another batch follows
hitslist
This batch of records
next_cursortext
Give this to the next Browse records; empty after the last batch
Example output
{
  "count": 4,
  "has_more": true,
  "hits": [
    {
      "name": "USB-C Charger",
      "objectID": "9077987002",
      "price": 24.99
    },
    {
      "name": "Wireless Mouse",
      "objectID": "ms-500",
      "price": 34.99
    },
    {
      "name": "Wireless Earbuds",
      "objectID": "eb-600",
      "price": 129.0
    },
    {
      "name": "Wireless Headphones",
      "objectID": "hp-100",
      "price": 69.99
    }
  ],
  "next_cursor": "AkFoaXRzUGVyUGFnZT00JmF0dHJpYnV0ZXNUb1JldHJpZXZlPSU1QiUyMm5hbWUlMjIlMkMlMjJwcmljZSUyMiU1RAEBBmhwLTEwMA=="
}

Clear an index

Delete every record in an index, keeping its settings, synonyms and rules. The API key needs the deleteIndex permission.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.

Outputs

index_nametext
The index cleared
records_deletednumber
How many records it held (null when the API key can't search)
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the change
Example output
{
  "index_name": "lodol_demo_products",
  "records_deleted": 4,
  "task_id": 1753626460002,
  "updated_at": "2026-10-02T22:38:06.875Z"
}

Copy or move an index

Copy an index, or only its settings, synonyms or rules, to another index, or move (rename) it. An index already at the destination is replaced. The index copied or moved must exist.

Inputs

From indexindex_nametextRequired
The index to copy or move.
To indexdestinationtextRequired
Where to copy or move it. An index of this name is replaced (only the parts copied, when copying some).
Copy or moveoperationtext
Copy leaves the original in place; move renames it.One of: copy, move (Move (rename)). Default: copy.
Copy onlyscopelist
Copy only these parts, not the records. Leave empty to copy everything, records included. A move always takes everything.One or more of: settings, synonyms, rules.

Outputs

destinationtext
Where it went
operationtext
copy or move
sourcetext
The index copied or moved
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the operation
Example output
{
  "destination": "lodol_demo_products_backup",
  "operation": "copy",
  "source": "lodol_demo_products",
  "task_id": 1753626449002,
  "updated_at": "2026-10-02T22:37:58.431Z"
}

Delete a record

Delete a record from an index by its object ID. A record that isn't there is not an error: deleted comes back false.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.
Object IDobject_idtextRequired
The record's object ID. A record an earlier step returned works too.

Outputs

deletedtrue/false
Whether there was such a record to delete
deleted_attext
When Algolia recorded the deletion
object_idtext
The record's object ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "deleted": true,
  "deleted_at": "2026-10-02T22:38:05.040Z",
  "object_id": "eb-600",
  "task_id": 1753626459002
}

Delete a rule

Delete a rule from an index by its ID. A rule that isn't there is not an error: deleted comes back false.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.
Rule IDrule_idtextRequired
The rule's ID, as Search rules returns it.
Apply to replicasforward_to_replicastrue/false
Also make the change on the index's replicas (its copies sorted another way). Off by default, as in Algolia.Default: false.

Outputs

deletedtrue/false
Whether there was such a rule to delete
rule_idtext
The rule's ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the deletion
Example output
{
  "deleted": true,
  "rule_id": "promote-earbuds",
  "task_id": 1753626450002,
  "updated_at": "2026-10-02T22:37:59.234Z"
}

Delete a synonym

Delete a synonym from an index by its ID. A synonym that isn't there is not an error: deleted comes back false.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.
Synonym IDsynonym_idtextRequired
The synonym's ID, as Search synonyms or Save a synonym returns it.
Apply to replicasforward_to_replicastrue/false
Also make the change on the index's replicas (its copies sorted another way). Off by default, as in Algolia.Default: false.

Outputs

deletedtrue/false
Whether there was such a synonym to delete
deleted_attext
When Algolia recorded the deletion
synonym_idtext
The synonym's ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "deleted": true,
  "deleted_at": "2026-10-02T22:38:01.077Z",
  "synonym_id": "lodol-synonym-6fc79aa2fef5",
  "task_id": 1753626452002
}

Delete an index

Delete an index with its records, settings, synonyms and rules. An index that doesn't exist is not an error: deleted comes back false. The API key needs the deleteIndex permission.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.

Outputs

deletedtrue/false
Whether there was such an index to delete
deleted_attext
When Algolia recorded the deletion
index_nametext
The index
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "deleted": true,
  "deleted_at": "2026-10-02T22:38:07.707Z",
  "index_name": "lodol_demo_products",
  "task_id": 1753626462002
}

Delete records

Delete up to 10,000 records from an index by their object IDs. IDs with no record are listed under not found.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.
Object IDsobject_idslistRequired
The records' object IDs, as a list or separated by commas. Records an earlier step returned work too.

Outputs

countnumber
How many records were deleted
deleted_object_idslist
Object IDs of the records deleted
not_foundlist
Object IDs the index had no record for
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "count": 1,
  "deleted_object_ids": [
    "sp-300"
  ],
  "not_found": [
    "zz-999"
  ],
  "task_id": 1753626456002
}

Delete records by filter

Delete every record matching a filter, like category:discontinued or stock = 0, and say how many matched. A filter on a text attribute the index can't filter on is reported instead of deleting nothing. The API key needs the deleteIndex permission.

Inputs

Indexindex_nametextRequired
The index to use. It must exist: Algolia would otherwise create an empty index of that name and report success, so a mistyped name is refused instead.
FiltersfilterstextRequired
Which records to delete, in Algolia filter syntax, like category:discontinued AND stock = 0. Search records with the same filters first to see what would go.

Outputs

matchednumber
How many records matched and were deleted (null when the API key can't search)
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the deletion
Example output
{
  "matched": 1,
  "task_id": 1753626454002,
  "updated_at": "2026-10-02T22:38:01.889Z"
}

Get a record

Retrieve one record from an index by its object ID.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Object IDobject_idtextRequired
The record's object ID. A record an earlier step returned works too.
Attributes to returnattributes_to_retrievelist
Attribute names to return for each record, like name and price. Leave empty for every attribute the index returns. The objectID always comes back.

Outputs

object_idtext
The record's object ID
recordobject
The record, with its objectID
Example output
{
  "object_id": "hp-100",
  "record": {
    "brand": "Sonance",
    "category": "Audio",
    "name": "Wireless Headphones",
    "objectID": "hp-100",
    "price": 69.99,
    "stock": 23,
    "tags": [
      "bluetooth"
    ]
  }
}

Get index settings

Get an index's settings, such as its searchable attributes, attributes for faceting and ranking, under Algolia's names.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.

Outputs

index_nametext
The index
settingsobject
The settings, like searchableAttributes, attributesForFaceting, customRanking and replicas
Example output
{
  "index_name": "lodol_demo_products",
  "settings": {
    "alternativesAsExact": [
      "ignorePlurals",
      "singleWordSynonym"
    ],
    "attributeForDistinct": null,
    "attributesForFaceting": [
      "searchable(brand)",
      "category",
      "filterOnly(price)"
    ],
    "attributesToHighlight": null,
    "attributesToRetrieve": null,
    "attributesToSnippet": null,
    "customRanking": [
      "desc(stock)"
    ],
    "exactOnSingleWordQuery": "attribute",
    "highlightPostTag": "</em>",
    "highlightPreTag": "<em>",
    "hitsPerPage": 20,
    "maxValuesPerFacet": 100,
    "minWordSizefor1Typo": 4,
    "minWordSizefor2Typos": 8,
    "numericAttributesToIndex": null,
    "optionalWords": null,
    "paginationLimitedTo": 1000,
    "queryType": "prefixLast",
    "ranking": [
      "typo",
      "geo",
      "words",
      "filters",
      "proximity",
      "attribute",
      "exact",
      "custom"
    ],
    "removeWordsIfNoResults": "none",
    "searchableAttributes": [
      "name",
      "brand",
      "category"
    ],
    "separatorsToIndex": "",
    "unretrievableAttributes": null,
    "version": 2
  }
}

Get recommendations

Get records Algolia Recommend suggests: related to a record, frequently bought with it, looking like it, or trending. The model must be set up and trained under Recommend in the Algolia dashboard.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Recommendationsmodeltext
Which Recommend model to ask (default related products).One of: related-products (Related products), bought-together (Frequently bought together), looking-similar (Looking similar), trending-items (Trending items). Default: related-products.
Object IDobject_idtext
The record to recommend from. Needed for every model but trending items.
How manymax_recommendationsnumber
How many records to return, from 1 to 30 (default 10).From 1 to 30. Default: 10.
Minimum scorethresholdnumber
Leave out recommendations Algolia scores below this, from 0 to 100 (default 0, every one).From 0 to 100. Default: 0.
Filtersfilterstext
Algolia filter syntax, like category:shoes AND price < 100, or (brand:Acme OR brand:Zenith) AND NOT discontinued:true. A text attribute must be listed in the index's attributes for faceting to be filtered on; a filter on one that isn't is reported rather than matching nothing.
Attributes to returnattributes_to_retrievelist
Attribute names to return for each record, like name and price. Leave empty for every attribute the index returns. The objectID always comes back.
Trending in facetfacet_nametext
For trending items: a faceted attribute to look within, like category.
Trending in valuefacet_valuetext
For trending items: the facet's value, like Shoes.

Outputs

countnumber
How many records came back
modeltext
The model asked
recommendationslist
The recommended records, best first, each with Algolia's _score (0 to 100)
Example output
{
  "count": 3,
  "model": "related-products",
  "recommendations": [
    {
      "_score": 50.7,
      "objectID": "media-sample-data-10193",
      "release_date": "2010-06-16",
      "title": "Toy Story 3",
      "vote_average": 7.811
    },
    {
      "_score": 49.39,
      "objectID": "media-sample-data-863",
      "release_date": "1999-10-30",
      "title": "Toy Story 2",
      "vote_average": 7.6
    },
    {
      "_score": 34.95,
      "objectID": "media-sample-data-979163",
      "release_date": "2022-06-10",
      "title": "Beyond Infinity: Buzz and the Journey to Lightyear",
      "vote_average": 7.0
    }
  ]
}

Get records

Retrieve several records from an index by their object IDs, up to 10,000. IDs with no record are listed under not found instead of failing the step.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Object IDsobject_idslistRequired
The records' object IDs, as a list or separated by commas. Records an earlier step returned work too.
Attributes to returnattributes_to_retrievelist
Attribute names to return for each record, like name and price. Leave empty for every attribute the index returns. The objectID always comes back.

Outputs

found_countnumber
How many records were found
not_foundlist
Object IDs the index has no record for
recordslist
The records found, in the order asked
Example output
{
  "found_count": 2,
  "not_found": [
    "zz-999"
  ],
  "records": [
    {
      "name": "Wireless Headphones",
      "objectID": "hp-100",
      "price": 69.99,
      "stock": 23
    },
    {
      "name": "Mechanical Keyboard",
      "objectID": "kb-400",
      "price": 129.0,
      "stock": 12
    }
  ]
}

Get search count

Count the searches on an index over a date range, in total and day by day, from Algolia Analytics. The API key needs the analytics permission.

Inputs

Indexindex_nametextRequired
The index whose searches to report on.
Fromstart_datedate
First day to report on. Leave empty for the last 8 days. Algolia's free plan keeps 7 days of analytics, paid plans longer.
Toend_datedate
Last day to report on. Leave empty for today.
Analytics regionregiontext
Where the application keeps its analytics and events, shown under Settings > Application in the Algolia dashboard. Most applications use the United States.One of: us (United States), de (Germany (EU)). Default: us.

Outputs

countnumber
Searches in the whole range
dateslist
Searches per day
end_datetext
Last day reported on, when given
start_datetext
First day reported on, when given
Example output
{
  "count": 5,
  "dates": [
    {
      "count": 0,
      "date": "2026-09-25"
    },
    {
      "count": 0,
      "date": "2026-09-26"
    },
    {
      "count": 0,
      "date": "2026-09-27"
    },
    {
      "count": 0,
      "date": "2026-09-28"
    },
    {
      "count": 0,
      "date": "2026-09-29"
    },
    {
      "count": 0,
      "date": "2026-09-30"
    },
    {
      "count": 0,
      "date": "2026-10-01"
    },
    {
      "count": 5,
      "date": "2026-10-02"
    }
  ],
  "end_date": "",
  "start_date": ""
}

Get searches without results

Get the most frequent searches on an index that found nothing, over a date range, from Algolia Analytics: a list of what people want and can't find. The API key needs the analytics permission.

Inputs

Indexindex_nametextRequired
The index whose searches to report on.
Fromstart_datedate
First day to report on. Leave empty for the last 8 days. Algolia's free plan keeps 7 days of analytics, paid plans longer.
Toend_datedate
Last day to report on. Leave empty for today.
How manylimitnumber
How many searches to return, from 1 to 1,000 (default 10).From 1 to 1000. Default: 10.
Analytics regionregiontext
Where the application keeps its analytics and events, shown under Settings > Application in the Algolia dashboard. Most applications use the United States.One of: us (United States), de (Germany (EU)). Default: us.

Outputs

end_datetext
Last day reported on, when given
searcheslist
The searches, most frequent first
start_datetext
First day reported on, when given
Example output
{
  "end_date": "",
  "searches": [
    {
      "count": 1,
      "search": "lamp",
      "with_filter_count": 0
    },
    {
      "count": 1,
      "search": "zzzqqq",
      "with_filter_count": 0
    }
  ],
  "start_date": ""
}

Get top searches

Get an index's most frequent searches over a date range from Algolia Analytics, with click and conversion rates when you send click events. The API key needs the analytics permission.

Inputs

Indexindex_nametextRequired
The index whose searches to report on.
Fromstart_datedate
First day to report on. Leave empty for the last 8 days. Algolia's free plan keeps 7 days of analytics, paid plans longer.
Toend_datedate
Last day to report on. Leave empty for today.
How manylimitnumber
How many searches to return, from 1 to 1,000 (default 10).From 1 to 1000. Default: 10.
Include click and conversion rateswith_click_analyticstrue/false
Add click-through rates, conversion rates and average click positions. They need click and conversion events sent for the index.Default: false.
Analytics regionregiontext
Where the application keeps its analytics and events, shown under Settings > Application in the Algolia dashboard. Most applications use the United States.One of: us (United States), de (Germany (EU)). Default: us.

Outputs

end_datetext
Last day reported on, when given
searcheslist
The searches, most frequent first
start_datetext
First day reported on, when given
Example output
{
  "end_date": "",
  "searches": [
    {
      "average_click_position": 1.0,
      "click_count": 1,
      "click_through_rate": 0.5,
      "conversion_count": 1,
      "conversion_rate": 0.5,
      "count": 2,
      "nb_hits": 1,
      "search": "desk",
      "tracked_search_count": 2
    },
    {
      "average_click_position": null,
      "click_count": 0,
      "click_through_rate": 0.0,
      "conversion_count": 0,
      "conversion_rate": 0.0,
      "count": 1,
      "nb_hits": 0,
      "search": "zzzqqq",
      "tracked_search_count": 1
    },
    {
      "average_click_position": null,
      "click_count": 0,
      "click_through_rate": 0.0,
      "conversion_count": 0,
      "conversion_rate": 0.0,
      "count": 1,
      "nb_hits": 0,
      "search": "lamp",
      "tracked_search_count": 1
    }
  ],
  "start_date": ""
}

List indices

List the indices in your Algolia application, with their record counts and sizes.

Inputs

None.

Outputs

countnumber
How many indices there are
indiceslist
The application's indices
Example output
{
  "count": 3,
  "indices": [
    {
      "created_at": "2026-07-24T20:02:18.542Z",
      "data_size": 26514404,
      "entries": 25115,
      "name": "algolia_movie_sample_dataset",
      "primary": "",
      "replicas": [],
      "updated_at": "2026-07-24T20:48:54.847Z"
    },
    {
      "created_at": "2026-10-02T22:37:42.412Z",
      "data_size": 670,
      "entries": 7,
      "name": "lodol_demo_products",
      "primary": "",
      "replicas": [],
      "updated_at": "2026-10-02T22:37:51.706Z"
    },
    {
      "created_at": "2026-10-02T22:14:23.511Z",
      "data_size": 234,
      "entries": 7,
      "name": "lodol_probe_algolia",
      "primary": "",
      "replicas": [],
      "updated_at": "2026-10-02T22:22:32.448Z"
    }
  ]
}

Save a rule

Add or replace a rule that pins records to the top of a search, hides records, applies filters or returns banner data: for searches matching a query, or for every search, and if you like only between two dates.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
Rule IDrule_idtextRequired
The rule's ID, like black-friday-tv; a rule with this ID is replaced.
When the searchquerytext
The search text the rule applies to, like tv. Leave empty to apply it to every search.
Matches howanchoringtext
How the search text must match (default: is exactly).One of: is (Is exactly), contains, startsWith (Starts with), endsWith (Ends with). Default: is.
Records to pinpromote_object_idslist
Object IDs of records to pin, in order, up to 300.
Pin from positionpromote_positionnumber
Where the pinned records start, counting from 0 for the top (default 0).From 0 to 299. Default: 0.
Records to hidehide_object_idslist
Object IDs of records to leave out of the results, up to 50.
Filters to applyfilterstext
Filters added to the search, in Algolia filter syntax, like brand:Acme.
Data to returnuser_dataobject
Data Algolia hands back with the results, for a banner or a redirect on your site, like {"banner": "Free shipping on TVs"}.
Descriptiondescriptiontext
A note on what the rule is for, shown in the Algolia dashboard.
Enabledenabledtrue/false
Whether the rule is on (default on).Default: true.
Active fromactive_fromdate and time
When the rule starts to apply. Leave empty for now.
Active untilactive_untildate and time
When the rule stops applying. Leave both dates empty for always.
Apply to replicasforward_to_replicastrue/false
Also make the change on the index's replicas (its copies sorted another way). Off by default, as in Algolia.Default: false.

Outputs

ruleobject
The rule as saved, in Algolia's format
rule_idtext
The rule's ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the change
Example output
{
  "rule": {
    "conditions": [
      {
        "alternatives": false,
        "anchoring": "contains",
        "pattern": "headphones"
      }
    ],
    "consequence": {
      "promote": [
        {
          "objectID": "eb-600",
          "position": 0
        }
      ],
      "userData": {
        "banner": "New: wireless earbuds"
      }
    },
    "description": "Pin the new earbuds to the top of headphone searches",
    "enabled": true,
    "objectID": "promote-earbuds",
    "validity": [
      {
        "from": 1790812800,
        "until": 1798761599
      }
    ]
  },
  "rule_id": "promote-earbuds",
  "task_id": 1753626446002,
  "updated_at": "2026-10-02T22:37:56.431Z"
}

Save a synonym

Add or replace a synonym on an index: words that find each other (two-way), a term that also finds other words (one-way), an alternative correction, or a placeholder.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
WordswordslistRequired
Two-way: every word that means the same, like sofa, couch and settee. One-way: the words the term also finds. Alternative correction: the corrections. Placeholder: what it stands for.
Typesynonym_typetext
What kind of synonym (default two-way).One of: synonym (Two-way: the words find each other), onewaysynonym (One-way: the term also finds the words), altcorrection1 (Alternative correction, ranked as 1 typo), altcorrection2 (Alternative correction, ranked as 2 typos), placeholder. Default: synonym.
Termtermtext
One-way: what people type, like phone. Alternative correction: the word to correct. Placeholder: its token in angle brackets, like <street>. Not used for two-way.
Synonym IDsynonym_idtext
The synonym's ID; one with this ID is replaced. Leave blank to make one from the words, so saving the same synonym again replaces it rather than adding a copy.
Apply to replicasforward_to_replicastrue/false
Also make the change on the index's replicas (its copies sorted another way). Off by default, as in Algolia.Default: false.

Outputs

synonymobject
The synonym as saved
synonym_idtext
The synonym's ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the change
Example output
{
  "synonym": {
    "corrections": [],
    "input": "",
    "objectID": "lodol-synonym-6fc79aa2fef5",
    "placeholder": "",
    "replacements": [],
    "synonyms": [
      "headphones",
      "headset",
      "earphones"
    ],
    "type": "synonym",
    "word": ""
  },
  "synonym_id": "lodol-synonym-6fc79aa2fef5",
  "task_id": 1753626445002,
  "updated_at": "2026-10-02T22:37:55.619Z"
}

Search facet values

Find the values of a faceted attribute that match some text, like the brands starting with 'app', with how many records hold each. The attribute must be searchable in the index's attributes for faceting, as searchable(brand).

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
FacetfacettextRequired
The faceted attribute whose values to search, like brand.
Value containsfacet_querytext
Text the values must match, as people type it (app finds Apple). Leave empty for the most common values.
Search textquerytext
Count only the records this search finds. Leave empty for every record.
Filtersfilterstext
Algolia filter syntax, like category:shoes AND price < 100, or (brand:Acme OR brand:Zenith) AND NOT discontinued:true. A text attribute must be listed in the index's attributes for faceting to be filtered on; a filter on one that isn't is reported rather than matching nothing.
How many valuesmax_facet_hitsnumber
How many values to return, from 1 to 100 (default 10).From 1 to 100. Default: 10.

Outputs

exhaustivetrue/false
Whether the counts are exact rather than estimated
facettext
The attribute searched
valueslist
Matching values, most records first
Example output
{
  "exhaustive": true,
  "facet": "brand",
  "values": [
    {
      "count": 3,
      "value": "Sonance"
    }
  ]
}

Search records

Search an index for records matching a query, narrowed with filters if you like (category:shoes AND price < 100), and count the values of facets such as brand. A search reaches the first 1,000 results at most; Browse records reads every record.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Search textquerytext
Text to search for. Leave empty to match every record, in the index's ranking order.
Filtersfilterstext
Algolia filter syntax, like category:shoes AND price < 100, or (brand:Acme OR brand:Zenith) AND NOT discontinued:true. A text attribute must be listed in the index's attributes for faceting to be filtered on; a filter on one that isn't is reported rather than matching nothing.
Results per pagehits_per_pagenumber
How many records to return, from 0 to 1,000 (default 20). 0 returns only the counts.From 0 to 1000. Default: 20.
Pagepagenumber
Which page of results to return, counting from 0.At least 0. Default: 0.
Attributes to returnattributes_to_retrievelist
Attribute names to return for each record, like name and price. Leave empty for every attribute the index returns. The objectID always comes back.
Facets to countfacetslist
Attributes whose values to count across every matching record, like brand or category; * counts every faceted attribute. They must be in the index's attributes for faceting.
Include match highlightsinclude_highlightstrue/false
Also return each record's _highlightResult and _snippetResult, which wrap the matched words in <em> tags.Default: false.
Count in Algolia Analyticscount_in_analyticstrue/false
Count this search in the index's Search Analytics. Off by default, so a workflow's searches don't mix with the searches people make.Default: false.

Outputs

facetsobject
For each facet counted, its values and how many matching records hold each, like {"brand": {"Acme": 12}}
hitslist
The matching records on this page, best first
hits_per_pagenumber
Records per page
nb_hitsnumber
How many records match in all
nb_pagesnumber
How many pages a search can reach at this page size
pagenumber
This page's number, from 0
processing_time_msnumber
How long Algolia took, in milliseconds
querytext
The text searched for
Example output
{
  "facets": {
    "brand": {
      "Keystone": 1,
      "Sonance": 2
    },
    "category": {
      "Audio": 2,
      "Computers": 1
    }
  },
  "hits": [
    {
      "brand": "Keystone",
      "name": "Wireless Mouse",
      "objectID": "ms-500",
      "price": 34.99,
      "stock": 42
    },
    {
      "brand": "Sonance",
      "name": "Wireless Earbuds",
      "objectID": "eb-600",
      "price": 129.0,
      "stock": 31
    }
  ],
  "hits_per_page": 2,
  "nb_hits": 3,
  "nb_pages": 2,
  "page": 0,
  "processing_time_ms": 1,
  "query": "wireless"
}

Search rules

List an index's rules, the changes Algolia makes to some searches (pinned or hidden records, filters, banners), or those matching some text.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Containingquerytext
Text in the rules' query, ID or description. Leave empty for all of them.
Pagepagenumber
Which page of results to return, counting from 0.At least 0. Default: 0.
Rules per pagehits_per_pagenumber
How many to return, from 1 to 1,000 (default 100).From 1 to 1000. Default: 100.

Outputs

nb_hitsnumber
How many rules match in all
nb_pagesnumber
How many pages there are
pagenumber
This page's number, from 0
ruleslist
The rules, as Algolia stores them: objectID, conditions, consequence, description, enabled and validity
Example output
{
  "nb_hits": 1,
  "nb_pages": 1,
  "page": 0,
  "rules": [
    {
      "_metadata": {
        "lastUpdate": 1790980676
      },
      "conditions": [
        {
          "alternatives": false,
          "anchoring": "contains",
          "pattern": "headphones"
        }
      ],
      "consequence": {
        "promote": [
          {
            "objectID": "eb-600",
            "position": 0
          }
        ],
        "userData": {
          "banner": "New: wireless earbuds"
        }
      },
      "description": "Pin the new earbuds to the top of headphone searches",
      "enabled": true,
      "objectID": "promote-earbuds",
      "validity": [
        {
          "from": 1790812800,
          "until": 1798761599
        }
      ]
    }
  ]
}

Search synonyms

List an index's synonyms, or those containing some text, optionally of one type.

Inputs

Indexindex_nametextRequired
The index to use. Index names are case-sensitive.
Containingquerytext
Text the synonyms must contain. Leave empty for all of them.
Typesynonym_typetext
Only synonyms of this type. Leave empty for every type.One of: synonym (Two-way), onewaysynonym (One-way), altcorrection1 (Alternative correction, 1 typo), altcorrection2 (Alternative correction, 2 typos), placeholder.
Pagepagenumber
Which page of results to return, counting from 0.At least 0. Default: 0.
Synonyms per pagehits_per_pagenumber
How many to return, from 1 to 1,000 (default 100).From 1 to 1000. Default: 100.

Outputs

nb_hitsnumber
How many synonyms match in all
synonymslist
The synonyms found
Example output
{
  "nb_hits": 1,
  "synonyms": [
    {
      "corrections": [],
      "input": "",
      "objectID": "lodol-synonym-6fc79aa2fef5",
      "placeholder": "",
      "replacements": [],
      "synonyms": [
        "headphones",
        "headset",
        "earphones"
      ],
      "type": "synonym",
      "word": ""
    }
  ]
}

Send an event

Tell Algolia a user viewed, clicked, added to cart or bought records, for Analytics, Recommend, Dynamic Re-Ranking and Personalization, for example a purchase when an order is paid.

Inputs

Eventevent_typetextRequired
What the user did.One of: view (Viewed), click (Clicked), conversion (Converted), add_to_cart (Added to cart), purchase (Purchased).
Event nameevent_nametextRequired
A name for this kind of event, up to 64 characters, like Product Purchased.
Indexindex_nametextRequired
The index the records belong to.
User tokenuser_tokentextRequired
Who did it: a user ID or an anonymous visitor ID, using only letters, digits and = + / _ -. Never an email address or other personal data.
Object IDsobject_idslistRequired
The object IDs of the records concerned, up to 20.
Search query IDquery_idtext
For a click or conversion after a search, the queryID that search returned, so Algolia credits it. Leave empty otherwise.
Positions clickedpositionslist
For a click with a search query ID: where each record appeared in the results, 1 for the first, one per object ID.
Valuevaluenumber
For an add to cart or a purchase, its total value, like 59.99.
Currencycurrencytext
The value's currency, as a three-letter code like USD.
Analytics regionregiontext
Where the application keeps its analytics and events, shown under Settings > Application in the Algolia dashboard. Most applications use the United States.One of: us (United States), de (Germany (EU)). Default: us.

Outputs

event_typetext
The event sent
messagetext
Algolia's answer, OK
senttrue/false
Whether Algolia took the event
Example output
{
  "event_type": "purchase",
  "message": "OK",
  "sent": true
}

Update a record

Change some attributes of a record and keep the rest. A value can also be an operation, like {"_operation": "Increment", "value": 1} for a stock count or AddUnique to add a tag to a list. A record that doesn't exist is added, unless Create if missing is off.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
Object IDobject_idtextRequired
The record's object ID. A record an earlier step returned works too.
Attributes to changeattributesobjectRequired
The attributes to set, like price: 59.99. The operations Increment, Decrement, Add, Remove, AddUnique, IncrementFrom and IncrementSet go as {"_operation": "Decrement", "value": 1}.
Create if missingcreate_if_missingtrue/false
Add the record when there is none with this object ID. Turn off to change only records that exist; updated then says whether one was changed.Default: true.

Outputs

object_idtext
The record's object ID
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updatedtrue/false
Whether the change was sent: false when the record didn't exist and Create if missing was off
updated_attext
When Algolia recorded the change
Example output
{
  "object_id": "hp-100",
  "task_id": 1753626440002,
  "updated": true,
  "updated_at": "2026-10-02T22:37:47.852Z"
}

Update index settings

Change some of an index's settings and keep the others, using Algolia's names, like {"attributesForFaceting": ["brand", "searchable(category)"]} or {"customRanking": ["desc(popularity)"]}.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
SettingssettingsobjectRequired
The settings to change, under Algolia's names: searchableAttributes, attributesForFaceting, customRanking, hitsPerPage and the rest. Settings left out stay as they are.
Apply to replicasforward_to_replicastrue/false
Also make the change on the index's replicas (its copies sorted another way). Off by default, as in Algolia.Default: false.

Outputs

index_nametext
The index changed
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
updated_attext
When Algolia recorded the change
Example output
{
  "index_name": "lodol_demo_products",
  "task_id": 1753626426002,
  "updated_at": "2026-10-02T22:37:43.209Z"
}

Update records

Change some attributes of up to 10,000 records at once, each given with its objectID, keeping their other attributes. Records that don't exist are added unless Create if missing is off; then they are listed under not found.

Inputs

Indexindex_nametextRequired
The index to write to. Algolia creates it on the first write if it doesn't exist.
ChangesrecordslistRequired
One object per record: its objectID and the attributes to set, which may use operations as in Update a record.
Create if missingcreate_if_missingtrue/false
Add records that don't exist. Turn off to change only records that do.Default: true.

Outputs

countnumber
How many records were changed
not_foundlist
Object IDs skipped because no such record exists (Create if missing off)
object_idslist
Object IDs of the records changed
task_idnumber
Algolia applies the change in the background; give this to Wait for a task to wait until it is searchable. 0 when nothing was sent.
Example output
{
  "count": 2,
  "not_found": [
    "zz-999"
  ],
  "object_ids": [
    "kb-400",
    "ms-500"
  ],
  "task_id": 1753626441002
}

Wait for a task

Wait until Algolia has applied a change, so the steps after it see it. Algolia applies writes in the background, usually within a few seconds. Give it the task ID (or the whole result) of the step that made the change.

Inputs

Indexindex_nametextRequired
The index the change was made to. For a copy or move, the index copied or moved.
Task IDtask_idnumberRequired
The task ID the change's step returned, or that step's whole result. 0 (a step that changed nothing) returns at once.
Wait at most (seconds)max_wait_secondsnumber
How long to wait before failing the step, from 1 to 300 seconds (default 60).From 1 to 300. Default: 60.

Outputs

publishedtrue/false
Whether the change is applied
statustext
published once the change is applied
task_idnumber
The task waited for
waited_secondsnumber
How long it took
Example output
{
  "published": true,
  "status": "published",
  "task_id": 1753626426002,
  "waited_seconds": 2.5
}

Alchemy

Previous Page

AltText.ai

Next Page

On this page

ActionsAdd or replace a recordAdd or replace recordsBrowse recordsClear an indexCopy or move an indexDelete a recordDelete a ruleDelete a synonymDelete an indexDelete recordsDelete records by filterGet a recordGet index settingsGet recommendationsGet recordsGet search countGet searches without resultsGet top searchesList indicesSave a ruleSave a synonymSearch facet valuesSearch recordsSearch rulesSearch synonymsSend an eventUpdate a recordUpdate index settingsUpdate recordsWait for a task