cribl-search-og (1)

Cribl Search - Searching Using the API

Last edited: January 22, 2025

This article aims to provide pointers on how to utilize the Cribl.Cloud API to perform Cribl Search queries in a systematic manner. This can be used for integrations with automation platforms or other external tools.

Creating Credentials

Cribl.Cloud’s login process over the API is a bit different than self-hosting. To do this, you must generate a Client ID and a Client Secret.

This can be done on the Cribl.Cloud console's Organization page. Once logged in, open the API Credentials section under the Organization tab. From there, click Add Credential with the needed permissions.

More Info: Cribl Docs

Logging into Cribl.Cloud

The login URL is the same for everyone: https://login.cribl.cloud/oauth/token.

The body of your request should be URL form-encoded, containing the following fields and values

Example curl request: (the credentials below are not real in case anyone gets any funny ideas)

curl -X POST 'https://login.cribl.cloud/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data 'client_id=ir5YRk2rHq7KvgwrDgaLMuMg3zLDKUxQ' \
--data 'client_secret=2VyZYXbLNzZtaBckZ7aA0fFR6bx59LRk8vn8nFmBUc5y4QDdtH2E4WJ8eVr44tvg' \
--data 'audience=https://api.cribl.cloud'

The response will look something similar to the following:

{
"access_token": "<<ACCESS_TOKEN>>",
"scope": "<<SCOPES>>",
"expires_in": 86400,
"token_type": "Bearer"
}

We will utilize the access token attribute in this response to authenticate further calls. Authentication is provided as a Header. The name of the header is Authorization, and the value will be Bearer <<ACCESS TOKEN FROM LOGIN REQUEST>>

Creating a Search

Two separate endpoints are used to create searches and obtain results. The first endpoint will create the search, which will look something like https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs.

The payload body sent to this endpoint will be a JSON object.

Note: that the query contains the cribl operator at the start, an operator is required at the beginning of the query.

{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1
}

Example curl request:

curl -X POST 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer << ACCESS TOKEN >>' \
--data-raw '{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
"earliest": "-1h",
"latest": "now",
"sampleRate": 1
}'

The returning payload will contain a lot of information about the search created, including its ID, which is required to obtain results.

{
"items": [
{
"query": "cribl dataset=\"cribl_search_sample\" | limit 1000",
...
"group": "default_search",
"id": "1732566655829.Z6s9KD",
"timeCreated": 1732566655887,
...
}
],
"count": 1
}

Waiting for the Search to Complete

To retrieve the result set, we must wait for the search to complete. A GET request against the status endpoint will provide information on the search.

Example curl request:

curl -X GET 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs/<< JOB ID >>/status' \
--header 'accept: application/x-ndjson' \
--header 'Authorization: Bearer << ACCESS TOKEN >>'

The response will contain a JSON object with an items array. Inside the array, an object with status information on the search is included. A status of completed indicates the search is complete.

{
"items": [
{
"status": "completed",
...
}
],
"count": 1
}

Obtaining Results

Once the job's status is completed, passing offset and limit as query string parameters will return the results in newline-delimited JSON format. Offset and limit values can be changed to make multiple requests to obtain the entire result set. Note that the first item returned is a status message with information about the search.

Example curl request:

curl -X GET 'https://main-incredible-swift-abc13ts.cribl.cloud/api/v1/m/default_search/search/jobs/<< JOB ID >>/results' \
--url-query 'offset=0' \
--url-query 'limit=100' \
--header 'accept: application/x-ndjson' \
--header 'Authorization: Bearer << ACCESS TOKEN >>'

Example Response:

{"isFinished":true,"limit":100,"offset":0,"persistedEventCount":1000,"totalEventCount":1000,"job":{"id":"1732566655829.Z6s9KD","query":"cribl dataset=\"cribl_search_sample\" | limit 1000","earliest":"-1h","latest":"now","timeCreated":1732566655887,"timeStarted":1732566656017,"timeCompleted":1732566670600,"status":"completed"}}
{"dataset":"cribl_search_sample","_raw":"2 602320997947 eni-0bf22c72ebe087ac9 172.16.2.199 10.0.0.33 1863 53 6 2 1684 1732566565 1732566601 ACCEPT OK","source":"s3://cribl-search-example/data/vpcflowlogs/2024/11/25/20/CriblOut-M3n9p5.1.raw.gz","dataSource":"vpcflowlogs","version":"2","account_id":"602320997947","interface_id":"eni-0bf22c72ebe087ac9","srcaddr":"172.16.2.199","dstaddr":"10.0.0.33","srcport":"1863","dstport":"53","protocol":"6","packets":"2","bytes":"1684","start":"1732566565","end":"1732566601","action":"ACCEPT","log_status":"OK","_time":1732566565,"datatype":"aws_vpcflow"}
{"dataset":"cribl_search_sample","_raw":"2 602320997947 eni-aay7nep03kqbijah0 10.0.0.164 10.8.90.201 5060 3389 6 20 26540 1732566559 1732566573 ACCEPT OK","source":"s3://cribl-search-example/data/vpcflowlogs/2024/11/25/20/CriblOut-DjmRA8.0.raw.gz","dataSource":"vpcflowlogs","version":"2","account_id":"602320997947","interface_id":"eni-aay7nep03kqbijah0","srcaddr":"10.0.0.164","dstaddr":"10.8.90.201","srcport":"5060","dstport":"3389","protocol":"6","packets":"20","bytes":"26540","start":"1732566559","end":"1732566573","action":"ACCEPT","log_status":"OK","_time":1732566559,"datatype":"aws_vpcflow"}

...

Cribl, the Data Engine for IT and Security, empowers organizations to transform their data strategy. Customers use Cribl’s suite of products to collect, process, route, and analyze all IT and security data, delivering the flexibility, choice, and control required to adapt to their ever-changing needs.

We offer free training, certifications, and a free tier across our products. Our community Slack features Cribl engineers, partners, and customers who can answer your questions as you get started and continue to build and evolve. We also offer a variety of hands-on Sandboxes for those interested in how companies globally leverage our products for their data challenges.

More from the blog

get started

Choose how to get started

See

Cribl

See demos by use case, by yourself or with one of our team.

Try

Cribl

Get hands-on with a Sandbox or guided Cloud Trial.

Free

Cribl

Process up to 1TB/day, no license required.