Create an Archive Search

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/logs/archive_searcheshttps://api.ap2.datadoghq.com/api/v2/logs/archive_searcheshttps://api.datadoghq.eu/api/v2/logs/archive_searcheshttps://api.ddog-gov.com/api/v2/logs/archive_searcheshttps://api.us2.ddog-gov.com/api/v2/logs/archive_searcheshttps://api.uk1.datadoghq.com/api/v2/logs/archive_searcheshttps://api.datadoghq.com/api/v2/logs/archive_searcheshttps://api.us3.datadoghq.com/api/v2/logs/archive_searcheshttps://api.us5.datadoghq.com/api/v2/logs/archive_searches

Overview

Start a search over the logs stored in an archive.

Without a rehydration object, the search only scans the archive and reports how much data matched. With one, the matched logs are also indexed into a retained historical view, which requires the logs_write_historical_view permission.

This endpoint requires any of the following permissions:
  • logs_write_historical_view
  • logs_write_archive_search

  • Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Archive Search object to create.

    attributes [required]

    object

    Attributes accepted when creating an Archive Search.

    archive_id [required]

    string

    ID of the archive to search. Use the Logs Archives API to list the archives of the organization.

    description

    string

    Free-text description of the Archive Search.

    from [required]

    date-time

    Start of the time range to search, as an ISO 8601 timestamp.

    name [required]

    string

    Name of the Archive Search.

    query [required]

    string

    Log search query used to filter the archived logs.

    rehydration

    object

    Rehydration settings. Include this object to index the matched logs into a retained historical view. Omit it to run an Archive Search that only scans the archive.

    max_rehydrated_events [required]

    int64

    Maximum number of events to rehydrate. The organization's reindexing limit is configured in millions, so this value is at least 1,000,000.

    retention_days [required]

    int64

    Number of days the rehydrated logs are retained for.

    tier [required]

    enum

    Storage tier the matched logs are rehydrated into. Allowed enum values: standard,flex

    to [required]

    date-time

    End of the time range to search, as an ISO 8601 timestamp. Must be after from.

    type [required]

    enum

    Archive Search resource type. Allowed enum values: archive_search

    default: archive_search

    {
      "data": {
        "attributes": {
          "archive_id": "mhmyYmyLTOaFYKvhNadu1w",
          "description": "Investigating the checkout latency spike.",
          "from": "2026-01-01T00:00:00Z",
          "name": "checkout-latency-investigation",
          "query": "service:checkout status:error",
          "rehydration": {
            "max_rehydrated_events": 1000000,
            "retention_days": 15,
            "tier": "standard"
          },
          "to": "2026-01-02T00:00:00Z"
        },
        "type": "archive_search"
      }
    }

    Response

    OK

    Response containing a single Archive Search.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    Archive Search object.

    attributes [required]

    object

    Attributes of an Archive Search.

    archive_id [required]

    string

    ID of the archive being searched.

    bytes_scanned [required]

    int64

    Number of bytes read from the archive at the end of the search.

    completed_at

    date-time

    Time the Archive Search finished, as an ISO 8601 timestamp. Absent while the search is still running.

    created_at [required]

    date-time

    Time the Archive Search was created, as an ISO 8601 timestamp.

    description

    string

    Free-text description of the Archive Search.

    events_scanned [required]

    int64

    Number of events read from the archive at the end of the search.

    expected_duration

    int64

    Estimated time left before the Archive Search completes, in seconds.

    from [required]

    date-time

    Start of the searched time range, as an ISO 8601 timestamp.

    name [required]

    string

    Name of the Archive Search.

    query [required]

    string

    Log search query used to filter the archived logs.

    rehydration

    object

    Rehydration settings of the Archive Search. Absent when the search only scans the archive without indexing the results.

    max_rehydrated_events [required]

    int64

    Maximum number of events to rehydrate.

    retention_days [required]

    int64

    Number of days the rehydrated logs are retained for.

    tier [required]

    enum

    Storage tier the matched logs are rehydrated into. Allowed enum values: standard,flex

    status [required]

    enum

    Current state of an Archive Search. Allowed enum values: RUNNING,COMPLETED,FAILED,CANCELLED,QUOTA_REACHED,EXPIRED

    to [required]

    date-time

    End of the searched time range, as an ISO 8601 timestamp.

    id [required]

    string

    Unique identifier of the Archive Search.

    type [required]

    enum

    Archive Search resource type. Allowed enum values: archive_search

    default: archive_search

    {
      "data": {
        "attributes": {
          "archive_id": "mhmyYmyLTOaFYKvhNadu1w",
          "bytes_scanned": 402764439,
          "completed_at": "2026-01-02T12:30:00Z",
          "created_at": "2026-01-02T12:00:00Z",
          "description": "Investigating the checkout latency spike.",
          "events_scanned": 1500,
          "expected_duration": 120,
          "from": "2026-01-01T00:00:00Z",
          "name": "checkout-latency-investigation",
          "query": "service:checkout status:error",
          "rehydration": {
            "max_rehydrated_events": 1000000,
            "retention_days": 15,
            "tier": "standard"
          },
          "status": "RUNNING",
          "to": "2026-01-02T00:00:00Z"
        },
        "id": "nv2eu4srgyzdkulggjzg2zkmmzifa2rum5iq",
        "type": "archive_search"
      }
    }

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Code Example

                      # Use a Personal Access Token or Service Access Token
    export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

    # Curl command
    curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/logs/archive_searches" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "archive_id": "mhmyYmyLTOaFYKvhNadu1w", "from": "2026-01-01T00:00:00Z", "name": "checkout-latency-investigation", "query": "service:checkout status:error", "rehydration": { "max_rehydrated_events": 1000000, "retention_days": 15, "tier": "standard" }, "to": "2026-01-02T00:00:00Z" }, "type": "archive_search" } } EOF
    """
    Create an Archive Search returns "OK" response
    """
    
    from os import environ
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.logs_archive_searches_api import LogsArchiveSearchesApi
    from datadog_api_client.v2.model.archive_search_create_rehydration import ArchiveSearchCreateRehydration
    from datadog_api_client.v2.model.archive_search_create_request import ArchiveSearchCreateRequest
    from datadog_api_client.v2.model.archive_search_create_request_attributes import ArchiveSearchCreateRequestAttributes
    from datadog_api_client.v2.model.archive_search_create_request_data import ArchiveSearchCreateRequestData
    from datadog_api_client.v2.model.archive_search_rehydration_tier import ArchiveSearchRehydrationTier
    from datadog_api_client.v2.model.archive_search_type import ArchiveSearchType
    from datetime import datetime
    from dateutil.tz import tzutc
    
    body = ArchiveSearchCreateRequest(
        data=ArchiveSearchCreateRequestData(
            attributes=ArchiveSearchCreateRequestAttributes(
                archive_id="mhmyYmyLTOaFYKvhNadu1w",
                description="Investigating the checkout latency spike.",
                _from=datetime(2026, 1, 1, 0, 0, tzinfo=tzutc()),
                name="checkout-latency-investigation",
                query="service:checkout status:error",
                rehydration=ArchiveSearchCreateRehydration(
                    max_rehydrated_events=1000000,
                    retention_days=15,
                    tier=ArchiveSearchRehydrationTier.STANDARD,
                ),
                to=datetime(2026, 1, 2, 0, 0, tzinfo=tzutc()),
            ),
            type=ArchiveSearchType.ARCHIVE_SEARCH,
        ),
    )
    
    configuration = Configuration()
    configuration.access_token = environ["DD_BEARER_TOKEN"]
    configuration.unstable_operations["create_archive_search"] = True
    with ApiClient(configuration) as api_client:
        api_instance = LogsArchiveSearchesApi(api_client)
        response = api_instance.create_archive_search(body=body)
    
        print(response)
    

    Instructions

    First install the library and its dependencies and then save the example to example.py and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
    # Create an Archive Search returns "OK" response
    
    require "datadog_api_client"
    DatadogAPIClient.configure do |config|
      config.access_token = ENV["DD_BEARER_TOKEN"]
      config.unstable_operations["v2.create_archive_search".to_sym] = true
    end
    api_instance = DatadogAPIClient::V2::LogsArchiveSearchesAPI.new
    
    body = DatadogAPIClient::V2::ArchiveSearchCreateRequest.new({
      data: DatadogAPIClient::V2::ArchiveSearchCreateRequestData.new({
        attributes: DatadogAPIClient::V2::ArchiveSearchCreateRequestAttributes.new({
          archive_id: "mhmyYmyLTOaFYKvhNadu1w",
          description: "Investigating the checkout latency spike.",
          from: "2026-01-01T00:00:00Z",
          name: "checkout-latency-investigation",
          query: "service:checkout status:error",
          rehydration: DatadogAPIClient::V2::ArchiveSearchCreateRehydration.new({
            max_rehydrated_events: 1000000,
            retention_days: 15,
            tier: DatadogAPIClient::V2::ArchiveSearchRehydrationTier::STANDARD,
          }),
          to: "2026-01-02T00:00:00Z",
        }),
        type: DatadogAPIClient::V2::ArchiveSearchType::ARCHIVE_SEARCH,
      }),
    })
    p api_instance.create_archive_search(body)
    

    Instructions

    First install the library and its dependencies and then save the example to example.rb and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
    // Create an Archive Search returns "OK" response
    
    package main
    
    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"
    	"time"
    
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
    )
    
    func main() {
    	body := datadogV2.ArchiveSearchCreateRequest{
    		Data: datadogV2.ArchiveSearchCreateRequestData{
    			Attributes: datadogV2.ArchiveSearchCreateRequestAttributes{
    				ArchiveId:   "mhmyYmyLTOaFYKvhNadu1w",
    				Description: datadog.PtrString("Investigating the checkout latency spike."),
    				From:        time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
    				Name:        "checkout-latency-investigation",
    				Query:       "service:checkout status:error",
    				Rehydration: &datadogV2.ArchiveSearchCreateRehydration{
    					MaxRehydratedEvents: 1000000,
    					RetentionDays:       15,
    					Tier:                datadogV2.ARCHIVESEARCHREHYDRATIONTIER_STANDARD,
    				},
    				To: time.Date(2026, 1, 2, 0, 0, 0, 0, time.UTC),
    			},
    			Type: datadogV2.ARCHIVESEARCHTYPE_ARCHIVE_SEARCH,
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
    	configuration := datadog.NewConfiguration()
    	configuration.SetUnstableOperationEnabled("v2.CreateArchiveSearch", true)
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewLogsArchiveSearchesApi(apiClient)
    	resp, r, err := api.CreateArchiveSearch(ctx, body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `LogsArchiveSearchesApi.CreateArchiveSearch`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `LogsArchiveSearchesApi.CreateArchiveSearch`:\n%s\n", responseContent)
    }
    

    Instructions

    First install the library and its dependencies and then save the example to main.go and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"
    // Create an Archive Search returns "OK" response
    
    import com.datadog.api.client.ApiClient;
    import com.datadog.api.client.ApiException;
    import com.datadog.api.client.v2.api.LogsArchiveSearchesApi;
    import com.datadog.api.client.v2.model.ArchiveSearchCreateRehydration;
    import com.datadog.api.client.v2.model.ArchiveSearchCreateRequest;
    import com.datadog.api.client.v2.model.ArchiveSearchCreateRequestAttributes;
    import com.datadog.api.client.v2.model.ArchiveSearchCreateRequestData;
    import com.datadog.api.client.v2.model.ArchiveSearchRehydrationTier;
    import com.datadog.api.client.v2.model.ArchiveSearchResponse;
    import com.datadog.api.client.v2.model.ArchiveSearchType;
    import java.time.OffsetDateTime;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
        defaultClient.setUnstableOperationEnabled("v2.createArchiveSearch", true);
        LogsArchiveSearchesApi apiInstance = new LogsArchiveSearchesApi(defaultClient);
    
        ArchiveSearchCreateRequest body =
            new ArchiveSearchCreateRequest()
                .data(
                    new ArchiveSearchCreateRequestData()
                        .attributes(
                            new ArchiveSearchCreateRequestAttributes()
                                .archiveId("mhmyYmyLTOaFYKvhNadu1w")
                                .description("Investigating the checkout latency spike.")
                                .from(OffsetDateTime.parse("2026-01-01T00:00:00Z"))
                                .name("checkout-latency-investigation")
                                .query("service:checkout status:error")
                                .rehydration(
                                    new ArchiveSearchCreateRehydration()
                                        .maxRehydratedEvents(1000000L)
                                        .retentionDays(15L)
                                        .tier(ArchiveSearchRehydrationTier.STANDARD))
                                .to(OffsetDateTime.parse("2026-01-02T00:00:00Z")))
                        .type(ArchiveSearchType.ARCHIVE_SEARCH));
    
        try {
          ArchiveSearchResponse result = apiInstance.createArchiveSearch(body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling LogsArchiveSearchesApi#createArchiveSearch");
          System.err.println("Status code: " + e.getCode());
          System.err.println("Reason: " + e.getResponseBody());
          System.err.println("Response headers: " + e.getResponseHeaders());
          e.printStackTrace();
        }
      }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to Example.java and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
    // Create an Archive Search returns "OK" response
    use chrono::{DateTime, Utc};
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_logs_archive_searches::LogsArchiveSearchesAPI;
    use datadog_api_client::datadogV2::model::ArchiveSearchCreateRehydration;
    use datadog_api_client::datadogV2::model::ArchiveSearchCreateRequest;
    use datadog_api_client::datadogV2::model::ArchiveSearchCreateRequestAttributes;
    use datadog_api_client::datadogV2::model::ArchiveSearchCreateRequestData;
    use datadog_api_client::datadogV2::model::ArchiveSearchRehydrationTier;
    use datadog_api_client::datadogV2::model::ArchiveSearchType;
    
    #[tokio::main]
    async fn main() {
        let body = ArchiveSearchCreateRequest::new(ArchiveSearchCreateRequestData::new(
            ArchiveSearchCreateRequestAttributes::new(
                "mhmyYmyLTOaFYKvhNadu1w".to_string(),
                DateTime::parse_from_rfc3339("2026-01-01T00:00:00+00:00")
                    .expect("Failed to parse datetime")
                    .with_timezone(&Utc),
                "checkout-latency-investigation".to_string(),
                "service:checkout status:error".to_string(),
                DateTime::parse_from_rfc3339("2026-01-02T00:00:00+00:00")
                    .expect("Failed to parse datetime")
                    .with_timezone(&Utc),
            )
            .description("Investigating the checkout latency spike.".to_string())
            .rehydration(ArchiveSearchCreateRehydration::new(
                1000000,
                15,
                ArchiveSearchRehydrationTier::STANDARD,
            )),
            ArchiveSearchType::ARCHIVE_SEARCH,
        ));
        let mut configuration = datadog::Configuration::new();
        configuration.set_unstable_operation_enabled("v2.create_archive_search", true);
        let api = LogsArchiveSearchesAPI::with_config(configuration);
        let resp = api.create_archive_search(body).await;
        if let Ok(value) = resp {
            println!("{:#?}", value);
        } else {
            println!("{:#?}", resp.unwrap_err());
        }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to src/main.rs and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run