API Usage & Credits

Overview

The LMCS API provides multiple link correction methods depending on your needs. You can choose to use our combined endpoint, or query engines individually. The multi-match endpoints can return multiple URL suggestions divided into "matches" and "semimatches" (possible alternatives), which is crucial if you want to create a "Did you mean to visit ...?" page.

URL matching endpoint

Endpoint URL: https://faray.tech/api/lmcscloud/urls/matches/best

This endpoint combines request validation, fast algorithmic multi-matching, and fallback LLM matching into a single flow.

The request validation ensures that URLs which are commonly visited by automated bots, that constantly scan the internet, are not matched. If the algorithm cannot find definitive matches, it falls back to the LLM to provide the best possible suggestion.

Pricing

Cost calculation

The cost is dynamic, you only pay for the phases that are actually executed. $0.0001 equals 1 credit.

The amount of characters that make up parts of the cost are calculated by accumulating:

  1. Sum of characters from the list of discoverable pages on your website
  2. Amount of characters from the incorrect URL the user has entered
mode value Validation phase Algorithm phase LLM phase
standard 1 credit 1 credit per 3,000 characters 1 credit per 500 characters
fast 1 credit 1 credit per 3,000 characters 3 credits per 500 characters
enhanced 1 credit 1 credit per 3,000 characters 15 credits per 500 characters
aggressive 1 credit 1 credit per 3,000 characters 15 credits per 500 characters

Cost calculation examples

We make the following assumptions:

  • mode standard is being used.
  • 60% of requests get thrown out at the validation phase.
  • 25% succeed at the algorithm phase.
  • the remaining 15% of requests reach the LLM phase.

Examples:

  • A normal corporate website like netcom-cs.de contain page names totalling about 2,500 characters.
    Realistic usage scenario (7k API requests per month): $1.4
  • Websites with lots of blog articles like nano-control.org contain page names totalling about 15,000 characters.
    Realistic usage scenario (7k API requests per month): $4.9
  • Large e-commerce sites like oceansapart.com contain page names totalling about 40,000 characters (when only using the page names from one language for the link correction) or 150,000 characters (using page names from all available languages for the link correction).
    Realistic usage scenario (133k API requests per month): $811.3

The amount of characters the user has entered in the URL is about 65 characters on average, which is negligible.

These sites are the property of their respective owners and are not affiliated with Faray Technologies. These sites have not endorsed the use of LinkAutocorrect.

Response latency

The delay between the API request and the response differs greatly depending on the amount of characters in the API request (see calculation above) and varies between each provider.
The response times should stay below 5 seconds if you keep the provider option set to auto.
We typically see a response time of 2 seconds for mode fast and 4 seconds otherwise.
Response times from our API will never exceed 30 seconds.

Request size limits

One character like c typically counts as one byte. Some characters like emojis 🌳 count as multiple bytes. However this shouldn't be relevant since emojis normally don't occur within URLs.

Provider /
modevalue		 auto OpenAI Google Groq
standard 395.000 bytes 395.000 bytes 395.000 bytes N/A
fast 395.000 bytes 395.000 bytes 395.000 bytes 60.000 bytes
enhanced 1.000.000 bytes 395.000 bytes 1.000.000 bytes 120.000 bytes
aggressive 1.000.000 bytes 395.000 bytes 1.000.000 bytes 120.000 bytes

All LLM-type endpoints feature a limit of 10,000 pages.

The size of a specific request does not affect your rate limit.

Rate-limits

Same rate-limits as the LLM-only endpoint.

Rate limit level Limits
Level 1 20 RPM | 150 RPH | 1,000 RPW
Level 2 50 RPM | 500 RPH | 10,000 RPW
Level 3 (default) 100 RPM | 1000 RPH | 10,000 RPD
Level 4 (available upon request) 200 RPM | 5000 RPH | 100,000 RPD
Level 5 500 RPM | 25000 RPH | 500,000 RPD

All faray.tech accounts have rate limit level 3 selected by default. You can manually set stricter rate limits if you prefer to do so. Please Contact us if you need a higher rate limit. After your rate limit level has been set to level 4 or higher, you cannot manually lower it.

Requests are counted with a sliding time window. This is different compared to a fixed time window that would reset to zero after the time period is over.

The amount of pages on your website and the selected mode do not affect the rate limit.

Input arguments

The endpoint accepts a JSON payload with the following arguments:

Parameter Type Required Description
input String Yes The incorrect URL path that the user attempted to visit.
pages Array or String Yes A list of valid, discoverable pages on your website. Can be an array of strings or one large newline-separated string. Maximum 10,000 pages.
mode String No The correction mode to use. Must be one of: standard, fast, enhanced, or aggressive. Defaults to standard.
algo String No Set the algorithm to use. Defaults to matchcore. Alternatively, you can specify damerau_levenshtein, or jaro_winkler.
provider String No Set the LLM provider to use. Defaults to auto. Alternatively, you can specify oai, google, or groq as the provider to use, however requests will simply fail if the selected provider has an outage.
user_ua String No The User-Agent of the client to validate against blocklists.
strip_exts Array No File extensions to strip from the each page name before matching.
reject_exts Array No File extensions that should cause pages to not be considered for matching.
block_output String No Configures the amount of additional information that is output for requests which failed the validity checks. Options: normal, standard, omit, debug.
validation_mode String No Limits request validation scope. Options: normal, uaonly (only verify the User-Agent), bponly (only verify the input path).
cms_installed Array No A list of CMS systems installed on your server (e.g., ["wp", "typo3"]) to set predefined path exclusions.

JSON Output

The endpoint returns a complex JSON response containing the match results, validity checks, and detailed metadata.

Field Type Description
success Boolean Returns true if the request was processed successfully.
validity Boolean Returns true if the request passed validation, or false if it was blocked.
match Boolean Returns true if the list of matches contains at least one entry.
matches Array A list of correct URL paths the user likely intended to visit, sorted with descending similarity to the provided input. If no match is found, this will be empty.
We recommend to automatically redirect users to the first element in this array and to only show a "Did you mean to visit ...?" page, if there are no matches.
semimatches Array A list of possible alternative URL paths that did not meet the strict match threshold. If no semimatch is found, this will be empty.
input String The original incorrect URL path provided in the request.
blockreason String (Optional) The reason the request was blocked (e.g., "blockedua", "blockedpath").
blockedfor Array (Optional) The specific rules that triggered the block.
error String (Optional) Contains an error message if the request failed.
metadata Object Detailed metadata about the request execution.
Meta Field Type Description
pages_amount Integer The number of pages processed.
cms_installed Array The validated list of CMS systems used for path blocking.
blocklists Object Information about the blocklists used. Format: filename => hash:%rules (the xxh3 hash of our internal block list file, useful to track changes over time, followed by the amount of rules).
strip_extensions / reject_extensions Array The sanitized extensions used during processing.
similarity_match_threshold / distance_match_threshold Float (Optional) The similarity score/distance threshold above which matches are counted.
similarity_semimatch_threshold / distance_semimatch_threshold Float (Optional) The similarity score/distance threshold above which semimatches are counted.
similarity_match_amount / distance_match_amount Integer (Optional) The number of matches found.
similarity_semimatch_amount / distance_semimatch_amount Integer (Optional) The number of semimatches found.
similarity_match_metric_best / distance_match_metric_best Float (Optional) The best algorithmic score across the set of matches.
similarity_semimatch_metric_best / distance_semimatch_metric_best Float (Optional) The best algorithmic score across the set of semimatches.
similarity_match_metric_avg / distance_match_metric_avg Float (Optional) The average algorithmic score from the set of matches.
similarity_semimatch_metric_avg / distance_semimatch_metric_avg Float (Optional) The average algorithmic score from the set of semimatches.
provider String (Optional) The LLM provider used (e.g., "oai") if fallback was triggered.
latency_ms Integer Total processing time in milliseconds.
cost Integer Total credits consumed by the request.
method String The engine that found the match: "none", "algo", or "llm".
mode String The mode used for the request.

Example responses

Example Output 1 (successful multi-match)

(
    [success] => true
    [validity] => true
    [match] => true
    [matches] =>
        (
            [0] => /products/laptops-13inch/
            [1] => /products/laptops-16inch/
        )
    [semimatches] =>
        (
            [0] => /products/laptops-all/
        )
    [input] => /products/laptops-14inch/
    [metadata] =>
        (
            [pages_amount] => 8
            [cms_installed] => ['wp']
            [blocklists] =>
                (
                    [blockedua] =>
                        (
                            [commonbots-fullstring-hashed.txt] => df8e1326ad3014b3:%43
                            [maliciousbots-fullstring-hashed.txt] => 97f5413a457aa694:%15
                            [maliciousbots-wildcard-hashed.txt] => 4a810bf527d20875:%14
                        )

                    [blockedpaths] =>
                        (
                            [arguments.txt] => 3126634b36652552:%10
                            [config-anywhere-block.txt] => 72f37d1fb5898179:%86
                            [general-anywhere-hardblock.txt] => 56a4cc45348b0bbe:%390
                            [general-rootdir-softblock.txt] => c8cede5cc5e5fc38:%791
                            [typo3.txt] => 2bcb0804b1e96067:%12
                            [wp.txt] => d60249f2ea529a58:%35
                        )
                )
            [strip_extensions] => []
            [reject_extensions] => []
            [similarity_match_threshold] => 0.85
            [similarity_semimatch_threshold] => 0.72
            [similarity_matches_amount] => 2
            [similarity_semimatches_amount] => 1
            [similarity_match_metric_best] => 0.9983
            [similarity_match_metric_avg] => 0.9965
            [similarity_semimatch_metric_best] => 0.8141
            [similarity_semimatch_metric_avg] => 0.8141
            [latency_ms] => 32
            [cost] => 2
            [method] => algo
            [mode] => fast
        )
)

Example Output 2 (blocked request)

(
    [success] => true
    [validity] => false
    [match] => false
    [blockreason] => blockedpath
    [blockedfor] =>
        (
            [0] => /(^|\/).*\.env($|\/)/i
        )
    [blockedpaths] =>
        (
            [0] => /db_backup.zip
            [1] => /functions.php
            [2] => /deploy.php
        )
    [matches] => []
    [semimatches] => []
    [input] => /.env
    [metadata] =>
        (
            [pages_amount] => 6
            [cms_installed] => []
            [blocklists] =>
                (
                    [blockedua] =>
                        (
                            [commonbots-fullstring-hashed.txt] => df8e1326ad3014b3:%43
                            [maliciousbots-fullstring-hashed.txt] => 97f5413a457aa694:%15
                            [maliciousbots-wildcard-hashed.txt] => 4a810bf527d20875:%14
                        )
                    [blockedpaths] =>
                        (
                            [arguments.txt] => 3126634b36652552:%10
                            [config-anywhere-block.txt] => 72f37d1fb5898179:%86
                            [general-anywhere-hardblock.txt] => 56a4cc45348b0bbe:%390
                            [general-rootdir-softblock.txt] => c8cede5cc5e5fc38:%791
                            [typo3.txt] => 2bcb0804b1e96067:%12
                            [wp.txt] => d60249f2ea529a58:%35
                        )
                )
            [strip_extensions] => []
            [reject_extensions] => []
            [latency_ms] => 34
            [cost] => 1
            [method] => none
            [mode] => standard
        )
)

Algorithm-only URL matching endpoint

Endpoint URL: https://faray.tech/api/lmcscloud/urls/matches/algo

This endpoint provides blazing fast, algorithmic multi-matching without validation steps. Our proprietary string-matching algorithm "matchcore" spanning across over 800 lines of code returns multiple highly relevant URL suggestions categorized into definitive matches and possible semimatches.

Pricing

The cost for an API request is 1 credit for every 3,000 characters.

The character count is the sum of characters from the list of discoverable pages plus the characters from the incorrect URL.

Response latency

This API endpoint is optimal for low-latency applications where consistent response times are crucial. Response times for requests larger than 200,000 bytes can exceed one second but always stay below five seconds.

Rate-limits

This endpoint offers significantly higher rate limits.

Rate limit level Limits
Level 1 50 RPM | 500 RPH | 10,000 RPW
Level 2 100 RPM | 1000 RPH | 10,000 RPD
Level 3 (default) 200 RPM | 5000 RPH | 100,000 RPD
Level 4 1000 RPM | 30000 RPH | 500,000 RPD
Level 5 3000 RPM | 100000 RPH | 2,500,000 RPD

Input arguments

The endpoint accepts a JSON payload with the following arguments:

Parameter Type Required Description
input String Yes The incorrect URL path that the user attempted to visit.
pages Array or String Yes A list of valid, discoverable pages on your website. Can be an array of strings or one large newline-separated string. Maximum 50,000 pages.
algo String No Set the algorithm to use. Defaults to matchcore. Alternatively, you can specify damerau_levenshtein, or jaro_winkler.

JSON Output

The endpoint returns a JSON response containing the match results and algorithmic metadata.

Field Type Description
success Boolean Returns true if the request was processed without any fatal errors.
match Boolean Returns true if at least one corrected URL was successfully identified based on the algorithm's threshold.
matches Array A list of correct URL paths the user likely intended to visit, sorted with descending similarity to the provided input. If no match is found, this will be empty.
We recommend to automatically redirect users to the first element in this array and to only show a "Did you mean to visit ...?" page, if there are no matches.
semimatches Array A list of possible alternative URL paths that did not meet the strict match threshold. If no semimatch is found, this will be empty.
input String The original incorrect URL path provided in the request.
metadata Object Detailed metadata about the request execution.
Meta Field Type Description
pages_amount Integer The number of pages processed.
similarity_match_threshold / distance_match_threshold Float The similarity score/distance threshold above which matches are counted.
similarity_semimatch_threshold / distance_semimatch_threshold Float The similarity score/distance threshold above which semimatches are counted.
similarity_match_amount / distance_match_amount Integer The number of matches found.
similarity_semimatch_amount / distance_semimatch_amount Integer The number of semimatches found.
similarity_match_metric_best / distance_match_metric_best Float The best algorithmic score across the set of matches.
similarity_semimatch_metric_best / distance_semimatch_metric_best Float The best algorithmic score across the set of semimatches.
similarity_match_metric_avg / distance_match_metric_avg Float The average algorithmic score from the set of matches.
similarity_semimatch_metric_avg / distance_semimatch_metric_avg Float The average algorithmic score from the set of semimatches.
latency_ms Integer Total processing time in milliseconds.
cost Integer Total credits consumed by the request.

Example Output

(
    [success] => 1
    [match] => 1
    [matches] =>
        (
            [0] => /us-en/printers/pagewide/managed-p55250dw
            [1] => /us-en/printers/pagewide/managed-p55250dn
        )
    [semimatches] =>
        (
            [0] => /us-en/printers/pagewide/managed-p77740z
        )
    [input] => /us-en/printers/widepage/mangaet-p55250dw
    [metadata] =>
        (
            [pages_amount] => 19
            [similarity_match_threshold] => 0.85
            [similarity_semimatch_threshold] => 0.72
            [similarity_matches_amount] => 2
            [similarity_semimatches_amount] => 1
            [similarity_match_metric_best] => 0.9863
            [similarity_match_metric_avg] => 0.9733
            [similarity_semimatch_metric_best] => 0.8231
            [similarity_semimatch_metric_avg] => 0.8231
            [latency_ms] => 97
            [cost] => 1
        )
)

The brand PageWide is the property of HP Inc. which is not affiliated with Faray Technologies.